# Troubleshooting

The known failure modes in one place: what the symptom means, and where the fix lives.

## Local development

- **`introspection local` reports no local runtime manifests were found.** The
  workspace has no runtime manifest. Create `.introspection/<runtime-slug>.yaml`
  at 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](/platform/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](/sdk/cli/local#what-a-save-changes).
- **An application reports `No local Recipe is connected`.** The target named
  in the message is only one part of the lookup. Confirm that
  `introspection dev` is still connected from the working tree for the same
  project, application agent, runtime group, and exact recipe commit as the
  task. If you used `--as`, set `INTROSPECTION_DEV_TARGET` in the application
  to that exact value and start a new task. API keys and service accounts may
  assert an end-user identity and still use their application's local recipe;
  a genuinely federated customer session is intentionally denied access to a
  developer's checkout. See
  [Cloud-connected development](/sdk/cli/local#cloud-connected-development).

## Sign-in and permissions

- **A request returns 403 "An active plan is required for `<scope>`".** The
  organization has no active plan, so members can only read organization
  settings. Choose one on the
  [plan page](https://app.introspection.dev/organization/plan). By contrast,
  `Missing required scope: <scope>` means your role or credential lacks that
  scope.
- **Creating an application returns 403 "Your plan can create service-account
  applications only".** Hosted login, federated, and native application types
  need a Max or Enterprise plan.
- **Native email-code sign-in returns 409 `account_exists`.** The email already
  belongs to another member of the organization. See
  [Native application](/platform/authentication#native-application).

## Tasks

- **A task never started, or stays queued.** Work through
  [Diagnosing a task](/platform/tasks-and-runs#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](/platform/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 `main` commit — see the
  [Quickstart](/start/quickstart#4-deploy-the-reviewed-recipe).
- **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](/guides/development-lifecycle#3-verify-the-committed-candidate-in-staging).

## Evals and judges

- **`judges add` cannot find a dataset.** Create the judge and its adjacent
  schema-v2 JSONL first with `introspection eval create <name> --with-judge`,
  then add a reviewed turn with an explicit `--expected` verdict — see
  [Calibrate judges](/guides/calibrate-judges#2-add-labelled-production-trajectories).
- **Vitest evals fail with a missing runner or adapter.** Pin compatible
  `vitest`, `vitest-evals`, and `@introspection-ai/vitest-evals` development
  dependencies in the eval package. See
  [Evaluate offline](/guides/evaluate-offline#3-add-representative-cases).
- **A replay fails with "could not locate Pi's installed package for
  conversation hydration".** The `pi` on `PATH` is the shell script pnpm writes
  to `node_modules/.bin/pi`, for example under `pnpm run` in a Recipe that has
  Pi as a development dependency. CLI 0.50.0 and later find that install. On
  CLI 0.46.0 to 0.49.1, set `INTROSPECTION_PI_CODING_AGENT_ROOT` to the
  `@earendil-works/pi-coding-agent` package directory, such as
  `node_modules/@earendil-works/pi-coding-agent` from the Recipe root.
- **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](/guides/experiments-and-shipping#3-create-a-bounded-comparison).

## 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](/guides/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](/platform/security#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](/support) — include the project, runtime, and task or conversation
id where you have one.

Troubleshooting

The known failure modes in one place: what the symptom means, and where the fix lives.

Local development

introspection local reports no local runtime manifests were found. The workspace has no runtime manifest. Create .introspection/<runtime-slug>.yaml at 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 reports No local Recipe is connected. The target named in the message is only one part of the lookup. Confirm that introspection dev is still connected from the working tree for the same project, application agent, runtime group, and exact recipe commit as the task. If you used --as, set INTROSPECTION_DEV_TARGET in the application to that exact value and start a new task. API keys and service accounts may assert an end-user identity and still use their application’s local recipe; a genuinely federated customer session is intentionally denied access to a developer’s checkout. See Cloud-connected development.

A request returns 403 “An active plan is required for <scope>”. The organization has no active plan, so members can only read organization settings. Choose one on the plan page . By contrast, Missing required scope: <scope> means your role or credential lacks that scope.
Creating an application returns 403 “Your plan can create service-account applications only”. Hosted login, federated, and native application types need a Max or Enterprise plan.
Native email-code sign-in returns 409 account_exists. The email already belongs to another member of the organization. See Native application.

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 main commit — 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

judges add cannot find a dataset. Create the judge and its adjacent schema-v2 JSONL first with introspection eval create <name> --with-judge, then add a reviewed turn with an explicit --expected verdict — see Calibrate judges.
Vitest evals fail with a missing runner or adapter. Pin compatible vitest, vitest-evals, and @introspection-ai/vitest-evals development dependencies in the eval package. See Evaluate offline.
A replay fails with “could not locate Pi’s installed package for conversation hydration”. The pi on PATH is the shell script pnpm writes to node_modules/.bin/pi, for example under pnpm run in a Recipe that has Pi as a development dependency. CLI 0.50.0 and later find that install. On CLI 0.46.0 to 0.49.1, set INTROSPECTION_PI_CODING_AGENT_ROOT to the @earendil-works/pi-coding-agent package directory, such as node_modules/@earendil-works/pi-coding-agent from the Recipe root.
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.