| title | Error Codes |
|---|
Structured JSON failures include error.code when the CLI can classify the recovery path. Agents and scripts should branch on error.code first, then error.message.
This catalog is the source of truth for stable codes. CI runs make snapshot-error-codes to assert that every Code: literal in internal/cli/*.go is documented here (or matches a documented dynamic prefix).
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
AUTH_UNAUTHENTICATED |
3 | No usable local session exists. | Run agora login. |
AUTH_SESSION_EXPIRED |
3 | The stored session is expired or rejected after refresh. | Run agora login again. |
AUTH_OAUTH_EXCHANGE_FAILED |
1 | The OAuth token endpoint rejected the authorization-code or refresh-token exchange. | Retry login; if persistent, file a bug with the HTTP status and request ID. |
AUTH_OAUTH_RESPONSE_INVALID |
1 | The OAuth token endpoint returned a response missing required token fields. | Retry login; if persistent, file a bug. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
PROJECT_NOT_SELECTED |
1 | No explicit, repo-local, or global project context is available. | Pass --project, work inside a bound quickstart, or run agora project use <project>. |
PROJECT_NOT_FOUND |
1 | The requested project ID or exact name was not found. | Run agora project list and retry with the project ID. |
PROJECT_AMBIGUOUS |
1 | A project name matched multiple projects. | Retry with the project ID. |
PROJECT_REGION_MISMATCH |
1 | A repo-local .agora/project.json binding points to a different region than the active login region. |
Run agora login --region <region> for the bound project region, or pass --project to override the repo-local binding. |
PROJECT_NO_CERTIFICATE |
1 | The selected project has no app certificate for env seeding. | Enable an app certificate in Console or select another project. |
PROJECT_ENV_TEMPLATE_UNKNOWN |
1 | The --template value for project env write is not supported. |
Use nextjs or standard. |
PROJECT_NOT_READY |
1 | project doctor could not surface a more specific issue. |
Re-run project doctor for details. |
PROJECT_TEMPLATE_UNKNOWN |
1 | project create --template is not a known project scenario preset. |
Use video-call or voice-agent; inspect agora introspect --json for the current catalog. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
QUICKSTART_TEMPLATE_UNKNOWN |
1 | The template ID is not known to this CLI. | Run agora quickstart list. |
QUICKSTART_TEMPLATE_REQUIRED |
1 | quickstart env write received --scenario without --template, and the target directory has no project binding or quickstart manifest to identify the template. |
Pass --template <id> or run from a quickstart directory with .agora/project.json or agora.quickstart.json. |
QUICKSTART_SCENARIO_UNKNOWN |
1 | The scenario is not known to this CLI. | Run agora quickstart list and use an items[].scenario value. |
QUICKSTART_SCENARIO_UNSUPPORTED |
1 | The scenario exists but is not supported by the selected template. | Choose a template/scenario pair returned by agora quickstart list. |
QUICKSTART_SELECTION_MISMATCH |
1 | Nonempty declarations in explicit flags, .agora/project.json, and agora.quickstart.json disagree about template/scenario identity; omitted fields inherit the existing selection. |
Correct the conflicting selection; do not overwrite env until all sources agree. |
QUICKSTART_MANIFEST_INVALID |
1 | agora.quickstart.json is malformed, uses an unsupported schema, has missing identity fields, or is required but absent. |
Restore a schema v1 manifest with template and scenario matching the quickstart. |
QUICKSTART_REQUIRED_FEATURE_MISSING |
— (retired) | Previously used by RTC onboarding previews; no longer returned by init when reusing a project. |
Initialization does not require feature enablement. Use agora project doctor --feature <feature> to check runtime readiness and project feature enable when needed. |
QUICKSTART_TEMPLATE_UNAVAILABLE |
1 | The template exists but is not currently available. | Choose an available template. |
QUICKSTART_TEMPLATE_ENV_UNSUPPORTED |
1 | The selected template does not define an env target path. | Choose a template with env support or configure the env file manually. |
QUICKSTART_PROJECT_REQUIRED |
1 | quickstart create could not resolve a project in a non-interactive run, or the account has no projects to select interactively. |
Pass --project, set global context with agora project use, use agora init, or explicitly pass --template-only. |
QUICKSTART_CREATE_ABORTED |
1 | The interactive quickstart project picker was canceled. | Re-run and select a project, or pass --template-only. |
QUICKSTART_TARGET_EXISTS |
1 | The clone target already exists. | Choose a new directory. |
QUICKSTART_REF_INVALID |
1 | --ref is empty after trimming, starts with -, or contains whitespace/control characters. |
Pass a valid git branch, tag, or commit (no leading -). |
QUICKSTART_REPO_OVERRIDE_INVALID |
1 | The AGORA_QUICKSTART_<TEMPLATE>_REPO_URL env override is set to a malformed value. |
Set the variable to an https://, ssh://, git://, file://, git@host:path, or absolute local path URL — or unset it. |
QUICKSTART_GIT_MISSING |
1 | git is required but was not found on PATH. |
Install git (https://git-scm.com/downloads) and retry. |
INIT_NAME_REQUIRED |
1 | agora init was run without the required target directory name. |
Pass a directory name, for example agora init my-nextjs-demo --template nextjs. |
INIT_SOURCE_REQUIRED |
1 | Non-interactive agora init received neither a quickstart template nor a recipe. |
Pass exactly one of --template <id> or --recipe <slug>. |
INIT_SOURCE_CONFLICT |
1 | agora init received both --template and --recipe. |
Pass only one initialization source. |
INIT_ABORTED |
1 | The interactive agora init reuse prompt was answered "no". |
Re-run with --project <id>, --new-project, or accept the prompt. |
PROJECT_NAME_REQUIRED |
1 | agora project create (or the equivalent MCP tool) was called without name. |
Pass a project name, for example agora project create my-app. |
RECIPE_TYPE_INVALID |
1 | The recipe type filter is not supported. | Use all, ai, or rtc. |
RECIPE_NOT_FOUND |
1 | The official recipes API did not contain the requested slug. | Run agora recipes list and retry with an available slug. |
RECIPE_API_FAILED |
1 | The recipes API could not be reached or returned a non-success status. | Check connectivity and retry; use AGORA_RECIPES_BASE_URL only for staging/testing. |
RECIPE_RESPONSE_INVALID |
1 | The recipes API response violated its documented schema or included a non-official entry. | Retry; if persistent, report the response schema mismatch. |
RECIPE_SCHEMA_UNSUPPORTED |
1 | The recipes API schema version is not supported by this CLI. | Upgrade the CLI. |
RECIPE_REPO_URL_INVALID |
1 | A recipe returned an invalid repository clone URL. | Report the catalog entry; do not clone it manually without verification. |
RECIPE_INIT_UNSUPPORTED |
1 | An official recipe can be viewed but does not yet include CLI env metadata. | Choose another recipe or follow its recipe document manually. |
These codes only appear from the agora upgrade self-update path on installer-managed installs. Homebrew, npm, and other managed channels do not emit upgrade error codes — they always return status: "manual" with a manager-specific command.
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
UPGRADE_NETWORK_FAILED |
1 | Could not query the GitHub API for the latest release. | Check connectivity; provide GITHUB_TOKEN if rate-limited. |
UPGRADE_DOWNLOAD_FAILED |
1 | Could not download the release archive or checksums.txt. |
Check connectivity; retry; pin a specific version in the release page if needed. |
UPGRADE_CHECKSUM_FAILED |
1 | The downloaded archive failed SHA-256 verification. | Do not continue; retry the download; inspect for a transparent proxy rewriting downloads. |
UPGRADE_EXTRACT_FAILED |
1 | The new binary could not be extracted from the archive. | File a bug with the archive contents. |
UPGRADE_BINARY_RESOLVE_FAILED |
1 | The CLI could not locate its own running executable. | Re-run with the absolute path to agora. |
UPGRADE_INSTALL_FAILED |
1 | The new binary could not replace the running one (typically a Windows file-in-use error or a non-writable install dir). | Close other agora processes, or run from an elevated shell, then retry. |
UPGRADE_UNSUPPORTED_PLATFORM |
1 | Self-update does not support the current OS/arch combination. | Use the platform installer manually. |
These codes appear inside data.checks[].issues[].code and (for blocking issues) propagate to the top-level error.code when JSON-mode project doctor exits non-zero.
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
WORKSPACE_SCAN_FAILED |
1 | project doctor --deep could not enumerate the repo workspace. |
Inspect the directory permissions and retry. |
LOCAL_PROJECT_BINDING_INVALID |
1 | .agora/project.json exists but is missing projectId. |
Re-bind the repo: agora project use <project> or agora init from the repo root. |
LOCAL_PROJECT_BINDING_MISMATCH |
1 | .agora/project.json points at a project that does not match the selected project. |
Use --project to select the bound project, or rebind. |
WORKSPACE_TEMPLATE_UNKNOWN |
2 (warning only) | Built-in quickstart layout checks do not cover this recipe or unrecognized workspace. | Inspect the recipe/workspace setup manually. project doctor has no --template flag. This warning does not override other blocking issues. |
WORKSPACE_ENV_PATH_UNKNOWN |
1 | The CLI could not determine the quickstart env target path. | Pass --template and re-run; if persistent, file an issue. |
WORKSPACE_ENV_FILE_MISSING |
1 | A quickstart env file expected by the bound template is missing. | Run the command from suggestedCommand (typically agora quickstart env write). |
WORKSPACE_ENV_READ_FAILED |
1 | The CLI could not read the quickstart env file. | Run the command from suggestedCommand (agora quickstart env write . --project <id>); if it still fails, inspect file permissions and contents. |
WORKSPACE_ENV_PROJECT_MISMATCH |
1 | The quickstart env file points at a different App ID than the selected project. | Run the command from suggestedCommand to overwrite the env file. |
WORKSPACE_ENV_APP_ID_MISSING |
1 | A quickstart env file is missing the required app ID key. | Run the command from suggestedCommand. |
WORKSPACE_ENV_APP_ID_MISMATCH |
1 | A quickstart env file points at a different app ID. | Run the command from suggestedCommand. |
APP_CREDENTIALS_MISSING |
1 | The selected project has no app ID / app certificate yet. | Run the command from suggestedCommand (agora project show --project <id>) to re-fetch credentials; if still missing, enable the app certificate in Console (agora open --target console). |
TOKEN_CAPABILITY_DISABLED |
(warning) | The project has token issuance disabled. | Enable token issuance in Console. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
SKILL_NOT_FOUND |
1 | agora skills show <id> was given an unknown skill ID. |
Run agora skills list to see available IDs. |
| Code | Exit | Meaning | Recovery |
|---|---|---|---|
WEBHOOK_FEATURE_REQUIRED |
1 | A project webhook command that needs --feature did not receive one. |
Pass --feature rtc, --feature rtm, or --feature convoai. |
WEBHOOK_FEATURE_INVALID |
1 | The --feature value is not a known CLI feature. |
Run agora introspect --json to inspect data.enums.features, then retry with a supported feature. |
WEBHOOK_CONFIG_ID_REQUIRED |
1 | A webhook command that needs a config ID did not receive a positive integer ID. | Pass the configId from agora project webhook list --feature <feature> --json. |
WEBHOOK_CONFIG_NOT_FOUND |
1 | The requested webhook config ID was not found in the backend response. | Run agora project webhook list --feature <feature> and retry with an existing configId. |
WEBHOOK_URL_REQUIRED |
1 | agora project webhook create did not receive a non-empty webhook endpoint URL. |
Pass --url https://.... |
WEBHOOK_EVENTS_REQUIRED |
1 | Create or update received no non-empty webhook event selections. | Run agora project webhook events --feature <feature> and pass one or more --event values. |
WEBHOOK_EVENT_UNKNOWN |
1 | An --event value did not match an event ID, event key, or exact display name for the selected feature. |
Run agora project webhook events --feature <feature> and retry with an items[].id or items[].key. |
WEBHOOK_EVENT_AMBIGUOUS |
1 | An --event value matched multiple webhook events. |
Retry with the numeric event ID from agora project webhook events --feature <feature>. |
WEBHOOK_SECRET_INVALID |
1 | The provided --secret does not match the backend secret pattern. |
Use 7-32 characters from A-Z, a-z, 0-9, _, or -; omit --secret to generate one. |
WEBHOOK_DELIVERY_REGION_INVALID |
1 | The provided --delivery-region is not supported. |
Use cn, sea, na, or eu. |
WEBHOOK_ENABLED_FLAG_CONFLICT |
1 | agora project webhook update received both --enabled and --disabled. |
Pass only one state flag. |
CONFIRMATION_REQUIRED |
1 | A destructive webhook operation was requested without explicit confirmation. | Pass --yes for CLI delete, or confirm:true for the MCP delete tool. |
Some doctor codes are generated from the feature name at runtime. Agents should match by prefix.
| Pattern | Example | Meaning | Recovery |
|---|---|---|---|
FEATURE_<NAME>_PROVISIONING |
FEATURE_RTC_PROVISIONING |
The named feature is being provisioned (warning). | Wait and re-run project doctor. |
FEATURE_<NAME>_DISABLED |
FEATURE_CONVOAI_DISABLED |
The named feature is disabled for this project. | Run the command from suggestedCommand or enable the feature in Console. |
INSTALL_DOCTOR_<STATUS> |
INSTALL_DOCTOR_NOT_READY |
agora doctor (top-level) summary code, where <STATUS> is WARNING, NOT_READY, or AUTH_ERROR. The detailed per-check items live in data.blockingIssues[].code / data.warnings[].code and follow the same dotted naming as project doctor codes (e.g. INSTALL_PATH_RESOLUTION, NETWORK_API_DNS). |
Read data.summary and the per-check suggestedCommand. |
<NAME> is uppercased and matches the feature ID set returned by agora introspect --json under data.enums.features (currently RTC, RTM, CONVOAI).
Failures returned by the Agora API preserve the upstream code, httpStatus, and requestId in the envelope when present. Agents should treat any error.code not in this catalog and not matching a dynamic prefix as a passthrough from the API and log/escalate it rather than handling it.
Common API error codes are not enumerated here because they may evolve independently of the CLI; consult the API documentation when handling them programmatically.