# Troubleshooting

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

## Common errors

| Error | Cause | Fix |
| --- | --- | --- |
| `422` from `connectors authorize` or `authorize-url` for Slack | A Slack connector needs the runtime that replies (`requires_runtime: true`). | Add `--runtime <runtime>`. |
| `409` when a new end user appears, or `402` when you bind a new Slack channel | The organization hit its [member limit](/reference/limits); every end user and Slack channel counts. Existing members keep working. | Prefer `user_id` over `anonymous_id`, or upgrade the plan. |
| Tasks stay `queued` during a burst | The organization's task concurrency is full (see [Limits](/reference/limits)). Retrying adds more queued work. | Let the queue drain, or shape the burst; contact support for more capacity. |
| Costs grow with traffic you did not expect | There are no spend or budget caps, and no per-user or per-key limit on creating tasks. | Throttle in your own backend (for example per end user) before calling the API. |
| Task fails with `byok_no_endpoints` | The runtime uses your own model keys (`llm_mode: byok`) but no `llm` endpoint is bound for that environment. | Bind one: see [Model access](/patterns/models#3-add-your-key-byok-only). |
| Task fails with `endpoint_credential_missing` | An endpoint header references a credential that is not set for that environment. | `introspection bindings credentials create ...` for that environment. |
| `introspection dev` exits with `dev_slot_conflict` | You already have `dev` attached for the same runtime and commit (another terminal or machine). `--as` does not change this. | Stop the other `dev`, or commit so the new session has a different commit. |
| `The local Recipe patch is N bytes, over the M byte cap` | `introspection dev` uploads a capped amount of local changes ([Limits](/reference/limits)). | Move large files out of the recipe directory, or add them to `.gitignore` or `.recipeignore`. |

## Local development

- **`introspection local` reports `No local Runtime manifests found`.**
  Create `.introspection/<runtime-slug>.yaml` at the repository root naming the
  recipe's path ([Runtimes](/ship)).
- **A saved change doesn't show up.** Skills reload live; prompt changes need a
  new conversation ([Develop locally](/build/local)).
- **An application reports `No local Recipe is connected`.** Keep `introspection dev`
  running for the task's project and runtime; with `--as`, set
  `INTROSPECTION_DEV_TARGET` to the same value. See [Develop locally](/build/local).

## Sign-in and permissions

- **A request returns 403 "An active plan is required for `<scope>`".** The
  organization has no active plan: choose one on the
  [plan page](https://app.introspection.dev/organization/plan).
  `Missing required scope: <scope>` means your role or credential lacks it.
- **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
  [Authentication](/reference/authentication#native-application-email-code-sign-in).

## Tasks

- **A task never started, or stays queued.** See
  [Task operations](/reference/task-operations).
- **A deployed agent behaves differently from the local run.** Check which
  version the task resolved (sticky per task) ([Runtimes](/ship)).

## Deploys and runtime versions

- **Staging ran a different version than the pull request.** Pin staging to the
  PR (`runtimes pin <id> --branch pr/<N>`) and check with `runtimes get`.

## Evals and judges

- **`judges add` cannot find the judge definition.** Run `introspection eval create <name> --with-judge` first ([Calibrate judges](/improve/judges)).
- **Vitest evals miss a runner or adapter.** Pin `vitest`, `vitest-evals`, and `@introspection-ai/vitest-evals` as dev dependencies.
- **A replay fails with "could not locate Pi's installed package".** Run
  `introspection setup`.
- **An experiment task has no `metadata.experiment_arm_id`.** It was not
  sampled and ran normal production. See
  [Experiment](/improve/experiments).

## Repository access

See [Repositories](/ship/repositories).

| 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. |
| `git clone` fails with `could not read Username` | The repository isn't granted to this runtime (or isn't registered to the project), so the sandbox has no credential for it. Grant it; requesting it on the task is only needed for an upfront clone. |
| `git push` fails with a permissions error | The runtime's `permissions` do not raise `contents` to `write`, or the GitHub App installation has not approved it. |
| Pushing to the recipe's own repository fails | The recipe can read its own repository but is not granted write. Name it in `repositories` to allow writes. See [Let an agent improve its own recipe](/ship/repositories#let-an-agent-improve-its-own-recipe). |

## Still stuck?

Email support@introspection.dev with 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.

Common errors

Error	Cause	Fix
`422` from `connectors authorize` or `authorize-url` for Slack	A Slack connector needs the runtime that replies (`requires_runtime: true`).	Add `--runtime <runtime>`.
`409` when a new end user appears, or `402` when you bind a new Slack channel	The organization hit its member limit; every end user and Slack channel counts. Existing members keep working.	Prefer `user_id` over `anonymous_id`, or upgrade the plan.
Tasks stay `queued` during a burst	The organization’s task concurrency is full (see Limits). Retrying adds more queued work.	Let the queue drain, or shape the burst; contact support for more capacity.
Costs grow with traffic you did not expect	There are no spend or budget caps, and no per-user or per-key limit on creating tasks.	Throttle in your own backend (for example per end user) before calling the API.
Task fails with `byok_no_endpoints`	The runtime uses your own model keys (`llm_mode: byok`) but no `llm` endpoint is bound for that environment.	Bind one: see Model access.
Task fails with `endpoint_credential_missing`	An endpoint header references a credential that is not set for that environment.	`introspection bindings credentials create ...` for that environment.
`introspection dev` exits with `dev_slot_conflict`	You already have `dev` attached for the same runtime and commit (another terminal or machine). `--as` does not change this.	Stop the other `dev`, or commit so the new session has a different commit.
`The local Recipe patch is N bytes, over the M byte cap`	`introspection dev` uploads a capped amount of local changes (Limits).	Move large files out of the recipe directory, or add them to `.gitignore` or `.recipeignore`.

Local development

introspection local reports No local Runtime manifests found. Create .introspection/<runtime-slug>.yaml at the repository root naming the recipe’s path (Runtimes).
A saved change doesn’t show up. Skills reload live; prompt changes need a new conversation (Develop locally).
An application reports No local Recipe is connected. Keep introspection dev running for the task’s project and runtime; with --as, set INTROSPECTION_DEV_TARGET to the same value. See Develop locally.

A request returns 403 “An active plan is required for <scope>”. The organization has no active plan: choose one on the plan page . Missing required scope: <scope> means your role or credential lacks it.
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 Authentication.

Tasks

A task never started, or stays queued. See Task operations.
A deployed agent behaves differently from the local run. Check which version the task resolved (sticky per task) (Runtimes).

Deploys and runtime versions

Staging ran a different version than the pull request. Pin staging to the PR (runtimes pin <id> --branch pr/<N>) and check with runtimes get.

Evals and judges

judges add cannot find the judge definition. Run introspection eval create <name> --with-judge first (Calibrate judges).
Vitest evals miss a runner or adapter. Pin vitest, vitest-evals, and @introspection-ai/vitest-evals as dev dependencies.
A replay fails with “could not locate Pi’s installed package”. Run introspection setup.
An experiment task has no metadata.experiment_arm_id. It was not sampled and ran normal production. See Experiment.

Repository access

See Repositories.

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.
`git clone` fails with `could not read Username`	The repository isn’t granted to this runtime (or isn’t registered to the project), so the sandbox has no credential for it. Grant it; requesting it on the task is only needed for an upfront clone.
`git push` fails with a permissions error	The runtime’s `permissions` do not raise `contents` to `write`, or the GitHub App installation has not approved it.
Pushing to the recipe’s own repository fails	The recipe can read its own repository but is not granted write. Name it in `repositories` to allow writes. See Let an agent improve its own recipe.

Still stuck?

Email support@introspection.dev with the project, runtime, and task or conversation ID where you have one.