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.
SSL Certificate Errors
Section titled “SSL Certificate Errors”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.
“API key not configured” Error
Section titled ““API key not configured” Error”If a tool raises BYTEPLUS_*_API_KEY is not configured, the server did not
find the credential in the environment. Check:
- The client points
ARK_MCP_ENV_FILEto the intended private file - The key name matches exactly (
BYTEPLUS_MODELARK_API_KEYorBYTEPLUS_SEED_SPEECH_API_KEY) - No leading/trailing whitespace in the value
- 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.
ark_job_capabilities Returns No Targets
Section titled “ark_job_capabilities Returns No Targets”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.
- Finish active jobs, then reconnect
ark-seedin the client you are using. Configuration is read at startup. Another editor’s running server does not prove this client’s connection is current. - Ask your setup agent to check the private-file path and permissions.
ARK_MCP_ENV_FILEmust be an absolute path on the actual execution host. Do not move keys into client JSON as a workaround. - Check only the product you need. Some tools need both a credential and a feature flag. Use Provider Keys and Configuration.
- 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.
Model Not Found / Not Activated
Section titled “Model Not Found / Not Activated”If the provider returns 403 FORBIDDEN with “model not activated”:
- Check the model ID in
.envmatches your console - Confirm the model is activated in your BytePlus region
- 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 URL Expired
Section titled “Provider URL Expired”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.
Artifact has persistence_error
Section titled “Artifact has persistence_error”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":uriis the temporary provider URL, valid untilpersistence_error.source_url_expires_at. Callseed_media_persist_urlwith thaturi,media_type,mime_type, andsource_expires_atbefore it expires. For Seedance and Seed 3D, polling the get tool again withpersist_output=truealso retries persistence.id="inline-fallback": the bytes are infallback_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.
output_path rejected or export_error set
Section titled “output_path rejected or export_error set”... is disabled: no output roots are configured: the client does not advertise MCP roots andOUTPUT_ROOTSis empty (a call insideark_job_submitnever has MCP roots). SetOUTPUT_ROOTSto 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 anOUTPUT_ROOTSentry.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: passoverwrite=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.
Seedance Task States
Section titled “Seedance Task States”| 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 |
Why is there no queue position or ETA?
Section titled “Why is there no queue position or ETA?”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.
Cannot Cancel or Delete
Section titled “Cannot Cancel or Delete”runningtasks cannot be cancelled or deleted — wait for completioncancelledtasks 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.
Timeout on Long Generations
Section titled “Timeout on Long Generations”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:
- Increase
BYTEPLUS_REQUEST_TIMEOUT_MS(orSEED_UNDERSTANDING_TIMEOUT_MSforseed_understandandseed_audio_understandonly) - Check your network connectivity to the BytePlus region
- Check
retryableandambiguous_completionon theTIMEOUTerror. 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_toto an absolute path (stdio, inside an output root) andreturn_content="none"or"summary"(first 2,000 characters). The full answer is written to disk;saved_pathandcontent_charstell you where and how long. - With a JSON
response_format,choices[].parsedis returned even whenreturn_contentisnone. - If the answer ends with
finish_reason="length", raisemax_tokens(it includes thinking tokens).json_retrydoes not retry truncated answers.
Client Timeouts vs Provider Latency
Section titled “Client Timeouts vs Provider Latency”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, andseed_audio_generatethrough theark_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/getat 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) orvod_get_task(VOD, with the echoedoperation) in the foreground; both default topersist_output=false. Then run the poller once throughark_job_submitwithpersist_output=trueto 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).
Client rejects task-augmented execution
Section titled “Client rejects task-augmented execution”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.
- Call
ark_job_capabilitiesand confirm the target is listed. - Call
ark_job_submitwith the target tool name and its original arguments. - Retain the returned Ark
job_idand pollark_job_getatpoll_after_msuntil terminal. - 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
Section titled “Background job is not available”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-mcpprocess. Eachstdioclient 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.
Artifacts Not Persisting
Section titled “Artifacts Not Persisting”Check:
ARTIFACT_DIRis writable- Disk has sufficient space
ARTIFACT_BACKENDisfilesystem, orobject_storagewith 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.
HTTP Server Refuses to Start
Section titled “HTTP Server Refuses to Start”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.
HTTP Authentication Fails
Section titled “HTTP Authentication Fails”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.
Unknown Tool over HTTP
Section titled “Unknown Tool over HTTP”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.
Moderation Lookup
Section titled “Moderation Lookup”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.
Running Tests
Section titled “Running Tests”make test # run all testsmake lint # ruff checkmake typecheck # mypyTests use respx and an autouse socket guard—real network calls fail the suite.