> For the complete documentation index, see [llms.txt](https://docs.khotan.com/llms.txt). A markdown version of any page is available at its `index.md` URL.

# Errors

When the CLI fails, it prints `error [code]` and a message. Do not invent flags. Use this table, then `khotan <command> --help`.

## `org_mismatch`

**Cause.** `KHOTAN_ORG_ID` or `--assert-org` is set, and `whoami.organizationId` does not match. Credentials point at a different organization.

**Next.** Stop. Do not infer anything from prior output. Fix `.env.khotan.local`, pass `--assert-org`, or select a per-customer profile. See [auth](/cli/auth/).

## `renamed_repo_env_file`

**Cause.** The repo holds an `env.khotan.local`. The credential file gained a leading dot and is now `.env.khotan.local`; the old name is no longer read.

**Next.** Rename it at the repo root: `mv env.khotan.local .env.khotan.local`. If both names are present, keep one and delete the other — which organization you would be acting against is otherwise ambiguous.

The old name is refused rather than ignored on purpose. That file carries `KHOTAN_ORG_ID`, so reading past it would skip the organization assertion and fall back to whatever profile is on the machine. See [auth](/cli/auth/).

## `confirmation_required`

**Cause.** A destructive command ran in a non-interactive session without `--yes`.

**Next.** Re-run with `--yes` only if you intend the destruction. See [safety](/cli/safety/).

## `workspace_git_stale`

**Cause.** A write or destructive command ran from a Khotan workspace whose
checkout is behind, diverged, or unverifiable against `origin/main`.

**Next.** Run `khotan workspace check --json`. Update or reconcile the checkout
yourself, then retry. Khotan never merges, rebases, resets, stashes, or changes
worktree files.

## `invalid_argument`

**Cause.** A flag or positional is missing, malformed, or the wrong type (`--folder-id` expects a value, `--env` expects `KEY=VALUE`).

**Next.** Run `khotan <command> --help`. Do not guess flag names.

## `unknown_capability`

**Cause.** The command is not in this CLI's catalog. The binary is older than the docs, or the command does not exist.

**Next.** Check `npm view @khotan/cli version`, upgrade, then `khotan help`.

## `unsupported_catalog_version`

**Cause.** The CLI read a catalog whose schema version it does not support.

**Next.** Upgrade the CLI. The error names both versions.

## `not_found`

**Cause.** The `/api/v1` envelope returned 404. The id does not exist in this organization.

**Next.** Confirm the id with a list command and that [org isolation](/cli/auth/) passed.

## `forbidden`

**Cause.** The `/api/v1` envelope returned 403. The key lacks permission, or deletion protection refused the delete.

**Next.** Do not retry with `--yes` as a workaround. Check the message; deletion protection must be disabled in the product, not on the CLI.