Skip to main content

​
Authentication

Three usual causes, in order of likelihood:
  1. The header is malformed. It must be exactly Authorization: Bearer <token> — one space, no quotes around the token.
  2. The token isn’t loading. Log whether your env var is defined (never its value). A missing .env in production is the classic version of this.
  3. The token was regenerated. Creating a new one doesn’t keep the old one alive. Update every place that used it.
Almost always the environment variable. .env files are typically not deployed — set the variable in your host’s configuration, then confirm the deployed process actually sees it.
201 from GET /auth-response/{request_id} means the key isn’t ready yet, not that something failed. Keep polling.

​
Runs

The deployment_id or run_id doesn’t exist, or doesn’t belong to your account. Check for a copy-paste truncation, and confirm you’re using a deployment ID rather than a workflow ID — they’re different things. See workflows & deployments.
Failures are usually the graph, not the platform. Check, in order:
  • Inputs — does workflow_inputs on the run match what you meant to send? The run echoes back what it actually received.
  • Reachability — was every input URL publicly reachable for the whole run? Expired signed URLs are a common culprit.
  • The graph by hand — run it manually in ComfyUI with the same inputs. If it fails there too, it’s the graph.
Confirm you’re treating uploading as non-terminal — a poll loop that only waits for running to end will appear to hang. Check started_at: if it’s null, the run is still queued and waiting on capacity, not stuck.
You read them too early. Outputs are written during uploading. Only read after success.
Compare workflow_version_id across the two runs — if they differ, a deployment changed underneath you. If they match, compare machine_id. Both are recorded on every run for exactly this.

​
Changes not taking effect

You didn’t deploy it. Saving a workflow in ComfyUI doesn’t change what your deployment_id points at. Deploy the new version — see workflows & deployments.
Input names are a contract. Renaming one breaks every existing caller. Either restore the old name or update all callers — and prefer deploying breaking changes as a new deployment.

​
Uploads

file_size must be the exact byte length of what you send. Use buffer.length or fs.statSync(path).size, not an estimate. Also confirm the MIME type matches the actual file.
Pass download_url as the input — not upload_url (write-only) and not file_id.

​
Local development

Another process holds that port. Stop it, or run on a different one:
Reinstall cleanly — delete node_modules and your lockfile, then npm install. If it persists, check the installed SDK version against the latest.

​
Reporting a problem

Include these and the answer comes back faster:
  • The run_id — it carries the version, machine, inputs, and timing
  • What you expected versus what happened
  • Whether the same graph works manually in ComfyUI
  • The status the run reached, and its started_at / ended_at
Never include your API token in a bug report, a screenshot, or a support message.