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.

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.

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.

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 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.