Troubleshooting
The known failure modes in one place: what the symptom means, and where the fix lives.
Local development
introspection localreports no local runtime manifests were found. The workspace has no runtime manifest. Create.introspection/<runtime-slug>.yamlat the repository root (or ask your coding agent to), naming the recipe’s path — the filename stem is the runtime slug you pass to--runtime. See Runtime manifest for the format.- A change you saved doesn’t show up in the session. Different recipe resources apply at different moments — skills reload live, prompt changes need a new chat. The authoritative table is What a save changes.
- An application isn’t reaching your
introspection devsession. Check the routing and failure rules in Cloud-connected development.
Tasks
- A task never started, or stays queued. Work through Diagnosing a task — the lifecycle states distinguish a startup failure from admission queueing.
- A deployed agent behaves differently from the local run. Confirm which runtime version the task resolved (resolution is sticky per task) and what its lane currently points at — see Runtimes.
Deploys and runtime versions
- The first deployed version went live in production, not just staging. The
first runtime version becomes active in both lanes; there is no staging-only
first bootstrap. Create it from a reviewed
maincommit — see the Quickstart. - Staging ran a different version than the pull request. The candidate is not pinned, or the runtime’s recipe commit doesn’t match the commit you intended to test. Verify both — see Verify the committed candidate in staging.
Evals and judges
conversations getdoesn’t produce a calibration dataset, orjudges evalrejects the export. Only--judge-fixtures(which requires--ids-file) produces fixtures, and every row lands with"expected": nulluntil a human labels it — see Calibrate judges.- Evalite evals fail with a missing
evalitebinary. The CLI resolvesevalitefrom the repository’s ownnode_modules/.bin, not a global install; pin it as a development dependency — see Evaluate offline. - An experiment task has no
metadata.experiment_arm_id. The subject fell outside the sample and received normal production, so the run is not experiment evidence — see Experiments and shipping.
Repository access
| Symptom | Cause |
|---|---|
A granted repository never appears in workspace/repos/ | It is not registered to the project, or the task did not request it. A grant alone clones nothing. See Work with repositories. |
| Registering returns 403 with a valid API key | Registration is member-authenticated. repositories:write is not an API-key scope. Use the dashboard or a logged-in CLI. |
Registering returns 409 repository_already_registered | The repository is already registered to this project. The list may have been stale, or someone else added it first. Nothing was changed. |
Unregistering returns 409 repository_in_use | Recipes are still pinned in that repository (the message names them), so removing it would leave them pointing at a tombstone and hard-fail every cold launch. Deleting a runtime does not delete its recipe. Delete the recipes (DELETE /v1/recipes/{id}), then unregister — that order is the one the guard enforces. Take the runtimes built from those recipes out of service first (DELETE /v1/runtimes/{id}, or PATCH {"yanked": true} to withdraw them from staging/production resolution): once their recipe is gone, /run returns 404. |
| A requested repository is missing, with the task running normally | It resolved outside the runtime’s grant, or its clone failed. Both drop the repository and continue. |
git clone of a granted repository fails with could not read Username | The task did not request it, so it has no in-sandbox credential. Add it to the task’s repositories. |
git push fails with a permissions error | The runtime’s permissions map does not elevate contents to write, or the App installation has not been approved for it. The mint refuses rather than narrowing. |
| Pushing to the recipe repository fails | It is entitled to clone itself but is not in the grant, so it stays read-only. Name it in repositories to allow writes — see self-improving agents. |
| A repository stopped resolving after someone unregistered it | Unregistering does not touch recipes. A grant that names an unregistered repository resolves to nothing, and its tasks launch without that checkout. Unregistering a repository a recipe is pinned in is refused outright, because that would fail the launch instead. |
| A repository in another GitHub organization cannot be granted | An Introspection organization connects one GitHub App installation today. |
| Pushes stopped creating runtime versions after the repository was renamed on GitHub | The registration still holds the old owner/name, and rename events are not handled. Register the new name and re-point the grant; a recipe pinned in the old row needs a new recipe against the new registration. |
Other repository bounds worth knowing:
- Neither the grant nor a task’s request has a count limit. What is rejected
is a list that cannot be right rather than one that is long: two entries naming
the same repository, or two repositories whose names collide on one
workspace/repos/<name>folder. - Every requested repository is cloned before the first turn, concurrently. Nothing caps that for you, so a long list is real startup latency you are choosing to spend.
- Workspace repositories are excluded from the baked image, so a cold launch always clones them fresh at the requested ref. A warm-storage restore or an in-place restart keeps the checkout already on disk rather than re-cloning it, so freshness comes from cold launches. On a baked runtime the clone is the dominant remaining startup cost.
- Personal access tokens are not a supported substitute for the App installation. A PAT can span GitHub organizations, but it reopens everything the App integration closes: manual rotation, no per-repository down-scoping at mint, and no installation-level audit trail.
Still stuck?
Get help — include the project, runtime, and task or conversation id where you have one.
Last updated on