comfyui-node

Acc. G-12 · v1.12.0

Troubleshooting

Common issues, diagnostics, and solutions for the ComfyUI SDK.

Table of Contents

Common Issues

SymptomLikely CauseFix
progress_pct never firesOnly listening to raw progress (or run finished instantly)Subscribe to progress_pct; ensure workflow isn't trivially cached/instant
Empty images arrayWrong node id in .output() or no SaveImage nodes detectedVerify node id in base JSON; omit outputs to let auto-detect run
_autoSeeds missingNo seed: -1 inputs presentSet seed field explicitly to -1 on nodes requiring randomization
Autocomplete missing for samplerUsed Workflow.from(...) not fromAugmentedSwitch to Workflow.fromAugmented(json)
Type not updating after new .output()Captured type alias before adding the callRecompute type R = ReturnType<typeof wf.typedResult> after last output declaration
Execution error but no missing outputsUnderlying node error surfaced via execution_error eventListen to failed + inspect error/server logs
Job hangs waiting for outputDeclared non-existent node idRun with fewer outputs or validate JSON; inspect _nodes metadata
Random seed not changing between runsProvided explicit numeric seedUse -1 sentinel or generate random seed before .set()
Preview frames never appearWorkflow lacks preview-capable nodes (e.g. KSampler)Confirm server emits b_preview events for your graph
Pool never selects idle clientMode set to PICK_LOWEST with constant queue depthSwitch to PICK_ZERO for latency focus
High-level run returns immediatelyAccessed await api.run(wf) only (acceptance barrier)Await job.done() or events to completion
Clients constantly disconnecting (idle)WebSocket inactivity timeout too aggressiveHealth checks enabled by default in v1.4.1+; verify not disabled
Connection stability issuesNetwork/firewall dropping idle connectionsEnsure healthCheckIntervalMs enabled (default 30s) in WorkflowPool

Error Types

The SDK raises specialized Error subclasses for better debuggability:

ErrorWhenKey Extras
EnqueueFailedErrorHTTP /prompt (append/queue) failedstatus, statusText, url, method, bodyJSON, bodyTextSnippet, reason
ExecutionFailedErrorExecution finished but not all mapped outputs arrivedmissing outputs context
ExecutionInterruptedErrorServer emitted interruption mid-runcause carries interruption detail
MissingNodeErrorDeclared bypass or output node is absentcause (optional)
WentMissingErrorJob disappeared from queue and no cached output–
FailedCacheErrorCached output retrieval failed–
CustomEventErrorServer emitted execution error eventevent payload in cause
DisconnectedErrorWebSocket disconnected mid-execution–

Error Codes

Every custom error exposes a stable code (enum) for branch logic without string matching:

ts
import { ErrorCode, EnqueueFailedError } from "comfyui-node";

try {
  await new CallWrapper(api, workflow).run();
} catch (e) {
  if ((e as any).code === ErrorCode.ENQUEUE_FAILED) {
    // inspect structured diagnostics
    const err = e as EnqueueFailedError;
    console.error('Status:', err.status, err.statusText);
    console.error('Reason:', err.reason);
    console.error('Body JSON:', err.bodyJSON);
    console.error('Snippet:', err.bodyTextSnippet);
  }
}

EnqueueFailedError Details

When the server rejects a workflow submission:

ts
try {
  await new CallWrapper(api, workflow).run();
} catch (e) {
  if (e instanceof EnqueueFailedError) {
    console.error('Status:', e.status, e.statusText);
    console.error('Reason:', e.reason);         // bodyJSON.error || bodyJSON.message || text snippet
    console.error('Body JSON:', e.bodyJSON);     // parsed JSON if available
    console.error('Snippet:', e.bodyTextSnippet); // first 500 chars of response
  }
}

reason is resolved using (in order):

  1. bodyJSON.error
  2. bodyJSON.message
  3. Truncated text body (first 500 chars)

This helps identify:

  • Mis-shaped prompts
  • Missing extensions
  • Permission issues
  • Model path problems

Execution Failure vs Interruption

  • ExecutionFailedError: Workflow ran but declared output nodes never produced data (often upstream node error). Check output mappings or inspect per-node errors.
  • ExecutionInterruptedError: Server/user actively interrupted execution. Retrying may succeed if cause was transient.

Testing & Coverage

This repository uses Bun's built-in test runner.

Test Scripts

bash
bun test                 # unit + lightweight integration tests
bun run test:real        # real server tests (COMFY_REAL=1)
bun run test:full        # comprehensive real server tests (COMFY_REAL=1 COMFY_FULL=1)
bun run coverage         # text coverage summary
bun run coverage:lcov    # generate coverage/lcov.info
bun run coverage:enforce # generate LCOV then enforce thresholds

Environment Flags

  • COMFY_REAL=1 – enables test/real.integration.spec.ts (expects running ComfyUI at http://localhost:8188 or COMFY_HOST)
  • COMFY_FULL=1 – additionally enables extended test/real.full.integration.spec.ts suite
  • COMFY_HOST=http://host:port – point at non-default instance

Coverage Thresholds

Enforced by scripts/coverage-check.ts:

Default thresholds:

  • Lines: >= 25%
  • Functions: >= 60%

Override thresholds:

bash
# Unix/macOS
COVERAGE_MIN_LINES=30 COVERAGE_MIN_FUNCTIONS=65 bun run coverage:enforce

# PowerShell
$env:COVERAGE_MIN_LINES=30; $env:COVERAGE_MIN_FUNCTIONS=65; bun run coverage:enforce

Improving Coverage

Current low-coverage areas:

  • src/client.ts – large surface; extract helpers & add unit tests
  • src/call-wrapper.ts – test error paths with mocked fetch & events
  • Feature modules with toleration logic (monitoring, manager, terminal)

Incremental strategy:

  1. Extract pure helper functions from monolithic classes
  2. Add fine-grained tests for error branches (non-200 responses, malformed JSON)
  3. Introduce deterministic mock WebSocket for replay testing
  4. Gradually raise thresholds by 5% after meaningful additions

Before opening PRs:

bash
bun test && bun run coverage

Diagnostic Tips

Enable Verbose Progress

bash
COMFY_PROGRESS_VERBOSE=1 bun run your-script.ts

Inspect Enqueue Failures

Check EnqueueFailedError fields:

  • status – HTTP status code
  • reason – extracted error message
  • bodyTextSnippet – first 500 chars of response

Verify Alias Mappings

ts
const result = await job.done();
console.log('Aliases:', result._aliases);
// { images: '9', sampler: '3' }

Check Auto Seeds

ts
console.log('Auto Seeds:', result._autoSeeds);
// { '3': 1234567 }

Type Staleness

If types feel stale, close & reopen the file – TypeScript sometimes caches deep conditional expansions.

Connection Issues

Monitor connection state:

ts
pool.on("client:state", (ev) => {
  console.log(`client ${ev.detail.clientId}: online=${ev.detail.online}, busy=${ev.detail.busy}`);
});

Check WebSocket activity:

ts
api.on('disconnected', () => console.log('WS disconnected'));
api.on('reconnected', () => console.log('WS reconnected'));

Debug Mode

Enable debug logging:

ts
const api = new ComfyApi('http://localhost:8188', undefined, {
  debug: true  // structured socket + polling logs
});

// or via environment:
// COMFY_DEBUG=1 bun run your-script.ts

Published Smoke Test

The script scripts/published-e2e.ts verifies the published npm artifact with Bun auto-install.

Quick Run (Auto-Install)

bash
mkdir comfyui-node-smoke
cd comfyui-node-smoke
curl -o published-e2e.ts https://raw.githubusercontent.com/igorls/comfyui-node/main/scripts/published-e2e.ts
COMFY_HOST=http://localhost:8188 bun run published-e2e.ts

Optional Explicit Install

bash
mkdir comfyui-node-smoke
cd comfyui-node-smoke
bun add comfyui-node
curl -o published-e2e.ts https://raw.githubusercontent.com/igorls/comfyui-node/main/scripts/published-e2e.ts
COMFY_HOST=http://localhost:8188 bun run published-e2e.ts

Environment Variables

VarDefaultPurpose
COMFY_HOSThttp://127.0.0.1:8188Base ComfyUI server
COMFY_MODELSDXL/sd_xl_base_1.0.safetensorsCheckpoint (must exist)
COMFY_POSITIVE_PROMPTscenic base promptPositive text
COMFY_NEGATIVE_PROMPTtext, watermarkNegative text
COMFY_SEEDrandomDeterministic seed override
COMFY_STEPS8Sampling steps
COMFY_CFG2CFG scale
COMFY_SAMPLERdpmpp_sdeSampler name
COMFY_SCHEDULERsgm_uniformScheduler name
COMFY_TIMEOUT_MS120000Overall timeout (ms)
COMFY_UPSCALEunsetIf set, adds RealESRGAN upscale
COMFY_MONITORunsetEnable Crystools monitor
COMFY_MONITOR_STRICTunsetFail if no monitor events

Exit codes:

  • 0: success
  • 1: import failure
  • 2: timeout
  • 3: enqueue failure
  • 4: other error
  • 5: monitor strict failure

Rationale

Ensures published dist is coherent and functional in clean consumer environment. Can be wired into CI behind opt-in flag.

Getting More Help

  1. Check existing documentation:

  2. Search existing issues: GitHub Issues

  3. Open a new issue: Provide:

    • SDK version
    • ComfyUI version
    • Minimal reproducible example
    • Error messages/stack traces
    • Environment (Node/Bun version, OS)
  4. Check ComfyUI logs: Often node errors appear in server console but not SDK events

Acc. G-12 · Edit docs/troubleshooting.md on GitHub