# Issue codes

Issues appear in the `issues` array of the [JSON envelope](/cli/json-envelope) and, for `pending` and `error`, on stderr.

## Prerequisites

| Code | Status | Meaning |
| --- | --- | --- |
| `dependency_missing` | `pending` | `agent-browser` or `shadcn` is not on PATH |
| `dependency_outdated` | `pending` | `agent-browser` or `shadcn` is older than the npm latest |
| `dependency_check_skipped` | `ok` | npm cannot be reached; mapping continues |

## Project and map

| Code | Status | Meaning |
| --- | --- | --- |
| `multiple_apps` | `pending` | More than one app under `--cwd` |
| `astro_not_supported` | `error` | The app is an Astro project |
| `stack_not_supported` | `error` | No supported framework was found |
| `invalid_package_json` | `ok` | A `package.json` cannot be read and was skipped |
| `manager_conflict` | `ok` | Evidence for more than one package manager |
| `unknown_screen` | `error` | `--screen` names a screen that is not in the map |
| `map_update_failed` | `error` | The map could not be written |
| `no_map` | `error` | `annotate` or `review` ran before any map exists |

## Annotations and reviews

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_annotation` | `error` | The annotation does not match its schema |
| `invalid_review` | `error` | The review does not match its schema |
| `identity_mismatch` | `error` | The declared session is not the session the host exposes |
| `stale_map` | `error` | The annotation was written against an older map revision |
| `stale_source` | `error` | Source hashes no longer match the files |
| `stale_annotation` | `error` | `expectedAnnotationRevision` is not the current revision |
| `stale_review` | `error` | The review targets another revision, or the annotation went stale |
| `unknown_subject` | `error` | The annotated subject is not in the map |
| `unknown_annotation` | `error` | The reviewed annotation is not in the map |
| `invalid_reference` | `error` | A source reference does not match a mapped file at its current hash |
| `self_review` | `error` | The author tried to review its own annotation |
| `disputed` | `pending` | The reviewer disputes the annotation; ask the user |
| `insufficient_evidence` | `pending` | The reviewer could not confirm it; gather more evidence |

## Command line

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_arguments` | `error` | Unknown flag, missing `--input`, or `--cwd` is not a directory |
| `invalid_input` | `error` | The `--input` file or stdin is not readable JSON |
| `unknown_command` | `error` | The command does not exist |