|Docs

Troubleshooting

Start with the smallest read-only checks:

Missing API key

Symptom:

Fix locally:

Fix in a remote/headless terminal:

Fix in CI:

Browser did not open

If sume login cannot open a browser, re-run with a device flow:

Open the printed URL/code locally, approve, then verify:

Wrong account or workspace

Check the configured context:

Then reset local auth if needed:

If SUME_API_KEY is set, it overrides local config. Unset it when testing local browser login:

Job created but no result yet

Jobs are async. Poll status:

Fetch the result only after terminal status:

For long video jobs, avoid tight polling loops. The CLI's --wait helpers use bounded intervals; agents can also use jobs.wait through MCP.

Generation command timed out

A CLI wait timeout does not necessarily mean the job failed. Inspect the job:

If the job is still running, continue polling at a longer interval. If it failed, report the sanitized error code/message and job id.

Upload failed

For uploads presign flows:

  1. Request a presign with an explicit --purpose.
  2. PUT bytes to upload_url with only required_headers.
  3. Do not send the Sume API Authorization header to the storage URL.
  4. Use assets finalize for asset_library_video.
  5. Use the returned Sume media URL for face_swap_source_video.

Never paste upload_url, object_key, or upload headers into public logs.

Download failed

jobs result --download and assets get --download download safe public media URLs returned by Sume.

If a download fails:

  • confirm the job or asset has media output;
  • retry once if the network failed;
  • use --json to inspect the result shape;
  • avoid printing full media URLs in bug reports.

MCP tool missing

Check discovery:

Then check the MCP gates:

Tool classRequired server flags
Default read toolssume mcp
Brand analyze / uploads / downloads--toolsets <toolset> --allow-write
Image/video/reference generation--toolsets generation --allow-paid
Ads / Face Swap--toolsets ads,face-swap --allow-paid

If a tool is available in schema discovery but not in the MCP client, restart the MCP server with the required toolset and gate.

CLI appears outdated

Check version and updates:

Install:

If the installed release does not include a command documented here, verify the release tag. These docs track the current SumeLabs/sume-cli release line and merged source; users may need the next CLI release for newly merged behavior.

What to include in a bug report

Include:

  • command name and flags, with secrets redacted;
  • sume --version;
  • sanitized error code/message;
  • request id if present;
  • job id if the issue is job-specific;
  • whether auth came from env or local config.

Do not include:

  • API keys;
  • login URLs or user codes;
  • signed upload URLs;
  • storage object keys;
  • full private media URLs;
  • raw provider payloads;
  • user/workspace ids unless engineering specifically asks for them.