# 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:

```bash
python -m pip show AbstractRuntime abstractcore
python -m pip install -U "abstractruntime[abstractcore]"
```

Fix:
- Install the matching optional extra for the surface you need:
  - `abstractruntime[abstractcore]` for LLM/tools integration.
  - `abstractruntime[multimodal]` for common image, voice, audio, and music dependencies.
  - `abstractruntime[mcp-worker]` for the MCP worker entry point.
- The current AbstractCore integration expects `abstractcore>=2.13.25`.

Verify:

```bash
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:

```python
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`, `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:

```bash
python -m pip install -U "abstractruntime[mcp-worker]"
abstractruntime-mcp-worker --help
```

Docs:
- `mcp-worker.md`

