Troubleshooting

This page is for symptom-oriented fixes. For concepts and limits, see faq.md; for setup and examples, see getting-started.md.

Importing abstractruntime.integrations.abstractcore fails

Symptom: - Importing the AbstractCore integration raises an ImportError about the required AbstractCore version or missing optional dependencies.

Checks:

python -m pip show AbstractRuntime abstractcore
python -m pip install -U abstractruntime

Fix: - Install or upgrade the base Runtime package. LLM/tools integration, common remote-light multimodal dependencies, and the MCP worker entry point are part of the base install. - The current AbstractCore integration expects abstractcore>=2.13.38.

Verify:

python -c "import abstractruntime.integrations.abstractcore as ac; print(ac.__all__[:5])"

A run is waiting and does not continue

Symptom: - Runtime.tick(...) returns status=waiting, and the run stays paused.

Likely causes: - The run is waiting for ASK_USER, WAIT_EVENT, passthrough tools, or tool approval. - WAIT_UNTIL needs a driver loop, or a host must call tick(...) again after the due time.

Fix: - For user/event/tool waits, resume with the exact wait_key from state.waiting.wait_key. - For time-based waits, use create_scheduled_runtime() or another host driver that periodically ticks due runs.

Verify:

state = rt.get_state(run_id)
print(state.status, state.waiting.wait_key if state.waiting else None)

Generated media is missing or too large for run state

Symptom: - Image, voice, music, or transcription outputs fail, or binary content is not present in RunState.vars.

Likely causes: - Generated binary outputs require a runtime ArtifactStore. - Runtime stores generated bytes by artifact reference instead of embedding raw bytes in checkpoints or ledger records.

Fix: - Construct the runtime with an artifact store such as InMemoryArtifactStore or FileArtifactStore. - Read artifact_id / artifact_ref from the durable result and load the artifact from the configured store.

Docs: - api.md#artifacts-store-by-reference - integrations/abstractcore.md#multimodal-generation

Remote media calls use the wrong model or fail with input-media errors

Symptom: - Remote image/TTS/STT calls do not use the expected media model. - Remote image generation fails when media is supplied. - Remote transcription rejects media that is not a local file or artifact-backed temporary file.

Fix: - Put endpoint-specific routing in the output selector, not in the chat model unless you intend to route chat. - Use output.task="image_edit" for image edits with one source image and optional mask. - Use exactly one audio media item for remote STT, and make sure it resolves to a local path or artifact-backed file.

Docs: - integrations/abstractcore.md#multimodal-generation

Local media residency returns model_residency_unsupported

Symptom: - A local MODEL_RESIDENCY load for image_generation, image_upscale, video_generation, text_to_video, image_to_video, tts, stt, or music_generation returns ok=false with code="model_residency_unsupported".

Meaning: - Runtime is reporting that the current local execution topology cannot truthfully keep that media backend resident for later reuse.

Fix: - Use a configured long-lived AbstractCore server for media residency, then let Runtime relay /acore/models/*. - Keep local media warmup optional (required=false) if it is only an optimization. - Do not infer loaded state from model defaults, catalogs, downloaded weights, or provider names.

Docs: - integrations/abstractcore.md#prompt-cache-control-plane-and-durable-blocs - faq.md#why-can-local-media-residency-return-okfalse-without-failing-the-run

Prompt-cache behavior is not reused for generated media

Symptom: - A workflow-level prompt-cache flag creates session cache keys for text/chat calls, but not for image, voice, music, or transcription output selectors.

Meaning: - Runtime only auto-derives session prompt-cache keys for text/chat calls. Non-text output selectors may still carry an explicit prompt_cache_binding, but Runtime does not invent one.

Fix: - Use params.prompt_cache_binding for durable exact text/chat prefix reuse. - Treat generated media calls as separate capability executions unless the selected AbstractCore backend documents a task-specific cache contract.

Docs: - integrations/abstractcore.md#prompt-cache-control-plane-and-durable-blocs - faq.md#where-should-cached-session-or-prompt-cache-state-live

MCP worker command is not found

Symptom: - abstractruntime-mcp-worker is not available on the command line.

Fix:

python -m pip install -U abstractruntime
abstractruntime-mcp-worker --help

Docs: - mcp-worker.md