Skip to content

Troubleshooting

Start with the symptom you see. You usually do not need to reinstall Ark or run server commands manually.

Symptom First thing to try
Ark is not listed in your client Review the client-specific MCP setup and unfinished approval steps
Connected, but tools are missing Reconnect after finishing active jobs; check requested services and private-file configuration
A request is still working Ask the client to poll the existing job/task, not submit it again
A shared server rejects access Ask its administrator to check the shared key, enabled products and fixed team permissions
You need help diagnosing local setup Ask your setup agent to inspect paths and settings metadata without printing secrets

Use the discovery-only check before any paid test. Never share populated credential files, full client configuration, raw environment dumps or unredacted logs in chat.

Ark already includes and enables truststore. If you see CERTIFICATE_VERIFY_FAILED, ask your setup agent to check that the client uses the documented python -m ark_mcp launch and the reviewed locked environment. Have your IT administrator check any corporate proxy or system certificate configuration. Do not disable TLS verification or independently add/upgrade dependencies to fix this.

If a tool raises BYTEPLUS_*_API_KEY is not configured, the server did not find the credential in the environment. Check:

  1. The client points ARK_MCP_ENV_FILE to the intended private file
  2. The key name matches exactly (BYTEPLUS_MODELARK_API_KEY or BYTEPLUS_SEED_SPEECH_API_KEY)
  3. No leading/trailing whitespace in the value
  4. The client was reconnected after saving the file, without interrupting active jobs

When a credential is absent, the server skips registering that product’s tools — it does not register a broken tool.

An empty targets list means your connection has no visible background targets. Locally, provider credentials or feature flags may be missing; on a shared server, fixed team scopes also exclude administrative tools.

  1. Finish active jobs, then reconnect ark-seed in the client you are using. Configuration is read at startup. Another editor’s running server does not prove this client’s connection is current.
  2. Ask your setup agent to check the private-file path and permissions. ARK_MCP_ENV_FILE must be an absolute path on the actual execution host. Do not move keys into client JSON as a workaround.
  3. Check only the product you need. Some tools need both a credential and a feature flag. Use Provider Keys and Configuration.
  4. Check inherited settings or shared-server permissions. An environment value can override the private file. Inspect names/presence without printing values; for shared deployments, ask the operator to check enabled products and the fixed team permissions.

Then repeat discovery. A startup warning about missing credentials is useful evidence, but absence of a warning is not proof that the right file was loaded.

If the provider returns 403 FORBIDDEN with “model not activated”:

  1. Check the model ID in .env matches your console
  2. Confirm the model is activated in your BytePlus region
  3. Verify the base URL matches your key’s region

Model IDs and access depend on your account and region. Ask your setup agent or administrator to compare discovery with the provider console before making another billable call. A local configuration check does not prove activation.

Provider output URLs expire:

  • Seed Audio: 2 hours
  • Seedream: 24 hours
  • Seedance: 24 hours (video and last-frame)

The server persists outputs immediately by default (persist=True) and returns seed-media://artifacts/{id} resource references that do not expire (until the artifact TTL, default 7 days).

If you set persist=False, the tool returns the raw provider URL which will expire. Use the artifact resource instead.

An ArtifactRef with persistence_error means the output was generated and billed but could not be stored durably (after download retries). The call still succeeded; nothing was lost yet:

  • id="provider-url": uri is the temporary provider URL, valid until persistence_error.source_url_expires_at. Call seed_media_persist_url with that uri, media_type, mime_type, and source_expires_at before it expires. For Seedance and Seed 3D, polling the get tool again with persist_output=true also retries persistence.
  • id="inline-fallback": the bytes are in fallback_data (Base64). Save them directly; they are not stored anywhere else.

Check persistence_error.code and retryable: output_too_large and untrusted_output_host will not succeed on retry; download_failed and storage_failed usually will. For persistent download timeouts, raise ARTIFACT_DOWNLOAD_TIMEOUT_SECONDS or ARTIFACT_DOWNLOAD_MAX_ATTEMPTS.

  • ... is disabled: no output roots are configured: the client does not advertise MCP roots and OUTPUT_ROOTS is empty (a call inside ark_job_submit never has MCP roots). Set OUTPUT_ROOTS to one or more absolute directories.
  • must be inside an allowed output root / must be an absolute path: use an absolute path under a client root or an OUTPUT_ROOTS entry.
  • only supported in stdio transport mode: local paths are stdio-only.
  • requires persist=true / requires persist_output=true: local copies are written from the durable artifact.
  • already exists with different content: pass overwrite=true.

Path errors are raised before the provider is called. A failed write after generation is reported in ArtifactRef.export_error instead; the durable artifact is unaffected and can be exported later with seed_media_export_artifact.

Status Meaning
queued Task is waiting to start
running Task is generating
succeeded Task completed, video available
failed Task failed, check error field
expired Task expired before completion
cancelled Task was cancelled via DELETE

ModelArk publishes no queue position or ETA for Seedance tasks. The queue field on each video task returned by gen_task_get is derived by the server from the task’s own timestamps: time queued, time running, service tier (flex usually queues longer), and expires_at, the time the provider fails an unfinished task (created_at + execution_expires_after; expires_at_estimated=true means the 48-hour default was assumed). Relay queue.hint to the user, and pass every task ID to one gen_task_get call until all_terminal is true.

  • running tasks cannot be cancelled or deleted — wait for completion
  • cancelled tasks cannot be deleted

The gen_task_cancel_or_delete tool (Seedance and 3D tasks) requires expected_status to match the actual status, preventing accidental destructive actions.

Seedream Pro and long Seed Audio generation can take 1-5 minutes. The default request timeout is 10 minutes (BYTEPLUS_REQUEST_TIMEOUT_MS=600000).

If you experience timeouts:

  1. Increase BYTEPLUS_REQUEST_TIMEOUT_MS (or SEED_UNDERSTANDING_TIMEOUT_MS for seed_understand and seed_audio_understand only)
  2. Check your network connectivity to the BytePlus region
  3. Check retryable and ambiguous_completion on the TIMEOUT error. What a timeout means depends on the call:
Call retryable ambiguous_completion Server retries? What to do
Create / generate / cancel / delete / MediaKit submit false true No It may have succeeded upstream. Do not retry blindly; reconcile by task ID, request ID, or client_token
Task polls (Seedance, Seed 3D, ASR query, MediaKit get) true false Yes Safe to poll again
ark_moderation_get true false No Honor retry guidance; another lookup consumes quota and its price is unspecified
seed_understand / seed_audio_understand chat completion true false No Safe to retry, but a retry is a new billed completion; consider a longer SEED_UNDERSTANDING_TIMEOUT_MS or lower reasoning_effort
Variation batch deadline see error.phase No queued (QUEUE_TIMEOUT) is safe to retry; generating is ambiguous

Budget reservations are committed for every TIMEOUT, since a timed-out call may still have been billed.

seed_understand Result Too Large or Missing Reasoning

Section titled “seed_understand Result Too Large or Missing Reasoning”

The reasoning trace is no longer returned: deep thinking is always on, but choices[].reasoning_content was removed and thinking is ignored. Only the final answer comes back; usage.reasoning_tokens reports thinking cost. If the answer itself is too large for the client context:

  • Set save_to to an absolute path (stdio, inside an output root) and return_content="none" or "summary" (first 2,000 characters). The full answer is written to disk; saved_path and content_chars tell you where and how long.
  • With a JSON response_format, choices[].parsed is returned even when return_content is none.
  • If the answer ends with finish_reason="length", raise max_tokens (it includes thinking tokens). json_retry does not retry truncated answers.

A client-side MCP timeout is distinct from a server failure. Seedream Pro and Seedance provider submissions can take 60–150 s (longer under cold start or provider queue), so the server requires background execution for those operations rather than keeping the original foreground request open.

  • Submit seedance_create_task, seedream_generate_image, and seed_audio_generate through the ark_job_* workflow below. Its terminal result contains the typed tool output.
  • On a task-capable client, you may instead invoke those tools with MCP task metadata, retain the returned MCP task ID, and poll tasks/get at the advertised interval until terminal.
  • For long video and VOD work, the background result contains the provider task ID. Poll gen_task_get (Seedance, 3D) or vod_get_task (VOD, with the echoed operation) in the foreground; both default to persist_output=false. Then run the poller once through ark_job_submit with persist_output=true to keep the outputs. Never resubmit the create tool to poll.
  • If a client disconnects after task acceptance, reconcile with the returned MCP task ID or provider task ID rather than resubmitting (see ambiguous_completion).

If Codex, Cursor, or another MCP client reports that the server requires task-augmented execution but its transport does not support it, do not call the required-task provider tool directly and do not switch it to foreground mode.

  1. Call ark_job_capabilities and confirm the target is listed.
  2. Call ark_job_submit with the target tool name and its original arguments.
  3. Retain the returned Ark job_id and poll ark_job_get at poll_after_ms until terminal.
  4. Read the original tool output from result.structured_content.

This remains a real background task on the same worker. For a Seedance, Seed 3D, or VOD submission, the provider task ID appears inside the completed original result and must be retained separately. A missing target usually means its provider credential or feature flag is unavailable, or the target is excluded from the fixed shared-team scopes.

Background job is not available in this server instance (local auth) or Background job is not available to this principal (shared-key auth) means the server answering the request cannot resolve the job ID. In local auth mode the caller is always the local principal, so the cause is process locality, not permissions:

  • The job was submitted by a different ark-mcp process. Each stdio client starts its own process; run one shared loopback HTTP server (make shared-http) and point all clients at it.
  • The server restarted: the default in-memory Docket backend discards active and retained jobs. Redis retention is the durability path.
  • The job ID is wrong, or its retained result expired.

In shared-key mode, the same message also covers jobs not owned by shared-team, including former user-owned or local jobs. Members of one team are not isolated from each other. Rotation keeps the team identity; changing auth modes does not transfer ownership. Preserve SQLite, Redis and the task encryption key when upgrading. The server deliberately does not distinguish missing, expired, and not-owned IDs, so do not probe for job existence.

Check:

  1. ARTIFACT_DIR is writable
  2. Disk has sufficient space
  3. ARTIFACT_BACKEND is filesystem, or object_storage with working TOS/S3 credentials

A storage failure no longer fails the tool call; look for persistence_error on the returned artifact (see above).

Run make check-env to validate configuration.

A non-loopback HTTP bind is rejected in local auth mode. Set MCP_AUTH_MODE=api_key and configure the lowercase SHA-256 digest MCP_API_KEY_SHA256 from scripts/generate_mcp_key.py. Do not put the raw key in server configuration. Add the public hostname to MCP_ALLOWED_HOSTS and browser origins to MCP_ALLOWED_ORIGINS.

The old jwt mode is rejected and its retired settings are not used. See breaking-change migration.

An HTTP 401 means the MCP key is missing, wrong or rotated out. Configure the current key privately as Authorization: Bearer <shared MCP key>; a BytePlus provider key is not a substitute. There is no login or discovery flow. After rotation, all clients need the new key, and the application must be recreated to load its new digest. Never paste either key into chat or logs.

Check ark_list_models.services and ark_job_capabilities for configured products and allowed background targets. The shared key’s ordinary scopes are fixed; clients cannot add scopes or select another identity. Account-wide asset and moderation tools are intentionally unavailable over shared HTTP, even if AK/SK or feature flags register them. Use a trusted local setup for administration rather than trying to grant a remote role.

ark_moderation_get requires BYTEPLUS_MODELARK_MODERATION_ENABLED=true (default off) and complete ModelArk AK/SK; STS also needs the session token. Use trusted stdio or local-mode loopback, not shared-key HTTP. Discovery’s moderation service reports configuration, not entitlement.

Symptom Meaning and action
Missing tool or denied over shared HTTP moderation:read is intentionally excluded; use a trusted local setup, not extra remote scopes
Missing from ark_job_capabilities or job/native-task rejection Foreground-only by design; call directly
Provider access denied Check Advanced Creation Rights, whitelist activation and IAM GetModerationResult; configuration does not verify them
INVALID_INPUT Use a bare provider ID and explicit task_id, asset_id or request_id; trimmed ID must be 1-256 characters without internal whitespace, controls or schemes; no extra fields
NotFound.Id May be invalid, unblocked, expired or ineligible; records must be within fourteen days and after whitelist activation. Text and regular 2.5 request-ID lookup are unsupported; use task_id for 2.5
LOCAL_RATE_LIMITED Ten lookups per rolling minute per runtime exhausted; no provider request sent. Honor retry delay
INVALID_RESPONSE Known provider response fields were malformed; retain only sanitized diagnostics, not raw bodies
Empty block_reasons Not proof of approval or safety; never automatically resubmit generation

There are no automatic retries or server-side lookup-result persistence. Live success remains unverified; 403, 404 or empty reasons do not validate it. For eligibility and isolated synthetic smoke instructions, see moderation.md. Do not share real IDs, reasons, fixtures, screenshots or restricted source material in public diagnostics.

Terminal window
make test # run all tests
make lint # ruff check
make typecheck # mypy

Tests use respx and an autouse socket guard—real network calls fail the suite.