# KANCLI Diagnostic Codes

Every diagnostic the CLI emits carries a stable `KANCLI###` code — in the terminal, in `doctor --json` output, and in exit behaviour. Codes never renumber, so they're the reliable thing to search for, put in a ticket, or gate CI on (message wording can change; the code can't). This page is the complete index, grouped by what you were doing when you hit it.

Three severities: **info** annotates, **warning** tells you something you should know but doesn't change the exit code, and **error** fails the command with a non-zero exit. `kanject doctor --json` emits them machine-readably (`schemaVersion: 1` envelope; severities `"info"` / `"warning"` / `"error"`):

```bash
kanject doctor --json --env stage | jq '.results[] | select(.severity == "error")'
```

> **Gaps are reserved, not missing:** Code numbers are allocated in themed bands with deliberate gaps for growth. A number you can't find here is either reserved, retired (kept for numbering stability, never emitted), or belongs to a band listed at the bottom of this page.

## Foundations & doctor (001–018)

- `KANCLI001` — .NET SDK version below the supported floor.
- `KANCLI002` — no `kanject-cli/manifest.json` found; run `kanject init` (or `cd` into the service).
- `KANCLI003` — lockfile drift: `manifest.lock.json` no longer matches the manifest. Run `kanject sync` and commit the result.
- `KANCLI004` — `Amazon.Lambda.Tools` missing or below the supported version.
- `KANCLI005` — `launchSettings.json` could not be parsed (`kanject test`).
- `KANCLI006` — the Lambda TestTool isn't installed (`kanject test`).
- `KANCLI007` — the named template wasn't found in the installed pack.
- `KANCLI008` — another kanject command holds this project's lock (`.kanject/.lock`); wait for it to finish.
- `KANCLI018` — the .NET global-tools directory is not on `PATH` — the classic *`kanject: command not found`* cause. Fix per-OS in [Troubleshooting](https://www.kanject.com/docs/cli-troubleshooting/).

## Cross-repo dependencies & sync (009–016, 190–199)

- `KANCLI009` — a declared dependency's project wasn't found in the cloned repo; check `projectPath`.
- `KANCLI010` — `git ls-remote` failed for a dependency repo; check the URL and your git credentials.
- `KANCLI012` — the declared `ref` (branch / tag / SHA) doesn't exist in the dependency repo.
- `KANCLI014` / `KANCLI015` — a git operation (clone / checkout) returned unexpected output or failed.
- `KANCLI190` — a transitive project reference isn't managed by the generated wiring (warning).
- `KANCLI191` — an existing `Directory.Build.*` file makes the generated-imports setup unsafe.
- `KANCLI192` — two dependency clones want conflicting versions (warning).
- `KANCLI193` — another sync is already running (advisory lock on `.sync.lock`).
- `KANCLI194` — two consumers would generate colliding import filenames.
- `KANCLI195` — git-hook install skipped: an existing hook manager (husky / lefthook) owns the hooks path.
- `KANCLI196` — `sync --locked` found drift between manifest and lockfile — the CI guard. Re-sync locally and commit the lock.
- `KANCLI198` / `KANCLI199` — `sync --offline` needed something not in the lock (198) or not in the cache (199); run one online sync first.

> **Seeing KANBUILD001–003 from MSBuild?:** Those three come from the generated build wiring, not the CLI itself: dependency cache missing (001), a dep's csproj missing (002), or lock drift detected at build time (003). All three have the same fix — run `kanject sync`.

## Manifest & entries (011, 013, 016, 050–058)

- `KANCLI011` — the manifest's `schemaVersion` isn't supported by this CLI version.
- `KANCLI013` — a stage listed in the manifest has no matching `stages/<stage>.json` file.
- `KANCLI016` — the manifest or a stage file contains an unknown field (strict parsing; check for typos).
- `KANCLI050` — an entry project's csproj is missing on disk.
- `KANCLI051` — two entries share the same id.
- `KANCLI052` — a v1 manifest could be upgraded to v2 (`kanject migrate --schema-v2`) — suggestion, not an error.
- `KANCLI053` — an entry has no `[LambdaFunction]`-decorated handler (warning).
- `KANCLI054` — the manifest declares no entries at all.
- `KANCLI055` — this code path supports single-entry services only.
- `KANCLI056` / `KANCLI058` — automatic v1→v2 loading found no csproj (056) or more than one candidate (058).
- `KANCLI057` — legacy `kanject/` directory detected; `git mv kanject kanject-cli`.

## Local dev: test, env & pull-env (041–045, 161)

- `KANCLI041` — the named launch profile doesn't exist.
- `KANCLI042` — the selected launch profile isn't a TestTool profile.
- `KANCLI043` — the IDE profile update couldn't find the TestTool entry.
- `KANCLI044` — `--pull-env` resolved SSM SecureString value(s) into the local process — a deliberate heads-up, not an error. Values stay in memory only.
- `KANCLI045` — `--pull-env` failed to resolve a reference (check IAM: `ssm:GetParameter`, `secretsmanager:GetSecretValue`).
- `KANCLI161` — `kanject env` omitted the stage when prompting was unavailable; pass `--env <stage>` in automation.

## Scaffolding: new, init, add, update (120–168, 022–023)

- `KANCLI120`–`KANCLI127` — `init` argument problems: invalid `--package-type` / `--schema`, no or duplicate stages, unknown default stage, mutually-exclusive flags, bad `--cwd`.
- `KANCLI128`–`KANCLI134` — `new` problems: mutually-exclusive flags, bad `--cwd`, template pack not installed, unknown template, `dotnet new` failed, runtime detection failed, manifest update failed.
- `KANCLI135`–`KANCLI137` — `update` problems: mutually-exclusive flags, CLI package update failed, template pack update failed.
- `KANCLI138`–`KANCLI144` — `add function` problems, including: the `source-generator` template can't be an entry (139), the target directory already exists (140), duplicate entry id (141).
- `KANCLI145`–`KANCLI148` — `add stage`: bad `--cwd`, invalid stage name (lowercase / digits / hyphens), stage already declared, stage file already exists.
- `KANCLI149`–`KANCLI160` — `add secret` / `add env` / `add lib` / `add param` missing-argument errors; notably `KANCLI154` — `KANJECT_`-prefixed env keys are reserved.
- `KANCLI162`–`KANCLI166` — `init --entry` overrides: bad format, duplicate id, path outside the project, not a Lambda project, stage-config conflict.
- `KANCLI167` — `add function` omitted its template or name when prompting was unavailable.
- `KANCLI168` — a destructive or mutating command requires explicit approval; `--non-interactive` and `--json` do not imply `--yes`.
- `KANCLI022` / `KANCLI023` — solution-file bootstrap failed (`dotnet new sln` / `dotnet sln add`).

## Plugins & providers (070–072, 170–188, 197)

- `KANCLI070` / `KANCLI071` — the manifest names an unknown (070) or empty (071) cloud provider.
- `KANCLI072` — installed provider plugin version doesn't match what the host requires.
- `KANCLI170`–`KANCLI175` — plugin load failures: assembly load, entry point missing / duplicated, ABI mismatch, instantiation, contract not implemented.
- `KANCLI176`–`KANCLI182` — `install provider` failures: unknown key, package not found, download / extract / post-install load failed, untrusted NuGet owner, or signed-manifest verification failed.
- `KANCLI183` — `install provider` omitted the key when prompting was unavailable, or supplied `--package` without an install key.
- `KANCLI186` / `KANCLI187` — provider auto-install declined at the prompt (186) or refused in a non-interactive shell (187; set `KANJECT_AUTO_INSTALL=1` in CI to pre-authorise).
- `KANCLI188` — the plugin exists but your license doesn't entitle it.
- `KANCLI197` — two installed plugins claim the same key.

## Stage config: configure vpc & domain (030–038, 080–085, 206)

- `KANCLI030`–`KANCLI033` — VPC validation: VPC missing, subnet or security group not in the VPC, subnets span only one AZ.
- `KANCLI034`–`KANCLI038` — domain validation: certificate in the wrong region or not covering the name, hosted-zone mismatch, invalid FQDN, invalid base path.
- `KANCLI080`–`KANCLI085` — `configure domain` / `configure vpc` argument errors (missing stage, `--clear` vs field flags, `--yes` without required flags).
- `KANCLI206` — the live EC2 network inventory couldn't be loaded for the interactive picker.

## Deploy (039–040, 060, 086, 103–114, 200–216)

- `KANCLI039` — a custom domain is configured but no API resource could be discovered to bind it to.
- `KANCLI040` — VPC config present but no `AWS::Serverless::Function` target — the silent-VPC-failure guard.
- `KANCLI060` — info: a hand-authored resource at a kanject-managed logical id was preserved, not overwritten.
- `KANCLI086` — `deploy` omitted the stage when prompting was unavailable; pass `--env <stage>` in automation.
- `KANCLI103`–`KANCLI108` — multi-entry template merge failures: no entries / resources / function, resource or output conflicts, multiple functions where one is expected.
- `KANCLI109`–`KANCLI114` — packaging and serverless-deploy runner failures (`dotnet lambda package-ci` / `deploy-serverless`), SAM preflight warnings (111–112).
- `KANCLI200`–`KANCLI203` — CloudFormation deploy failed, change-set failed, deploy timeout, resource not found during the alias flip.
- `KANCLI209`–`KANCLI216` — artifact-path failures: `--no-build` packaging, serverless base-template problems, `aws template migrate` preconditions, unsupported target framework, env overlay failure.

## Rollback & deployments (087–095, 116–119, 207–208, 418–420, 463–464)

- `KANCLI087` / `KANCLI088` — `rollback` needs `--env`; and in a non-TTY shell, an explicit `--to`.
- `KANCLI091`–`KANCLI095` — `deployments` argument errors: missing stage / ref / mark args, S3 write failed, unknown action.
- `KANCLI116`–`KANCLI118` — nothing to roll back to: no previous version (116), no previous *stable* version (117), or the named version doesn't exist (118).
- `KANCLI119` — `deployments mark` only accepts `stable` or `broken`.
- `KANCLI207` — the rollback target's artifacts were pruned by retention; pick another revision.
- `KANCLI208` — a multi-entry rollback partially applied — inspect before retrying.
- `KANCLI418` — the deploy promoted but the ledger write failed; reconcile before the next deploy.
- `KANCLI419` / `KANCLI420` — ledger reconciliation: live stack diverged from the active pointer (419); ledger namespace collision (420).
- `KANCLI463` / `KANCLI464` — `deployments gc`: sweep blocked by an in-flight operation (463) or partially failed (464).

## Preview stacks (089–090, 115, 204–205)

- `KANCLI089` — `preview rm` needs a name or `--expired`.
- `KANCLI090` — previews aren't enabled: set `preview.enabled: true` in the manifest.
- `KANCLI115` — `preview extend` couldn't find the named stack.
- `KANCLI204` — `extend` refused: the stack isn't tagged `kanject:preview=true` — real stages can't enter the preview TTL lifecycle.
- `KANCLI205` — invalid `--by` duration (use forms like `7d`, `24h`, `30m`).

## Pipeline (096–097, 310–317)

- `KANCLI096` / `KANCLI097` — `pipeline bootstrap`: template not found / required flag missing.
- `KANCLI310`–`KANCLI313` — `pipeline up` preflight: AWS credentials invalid, CodeStar connection not ready (authorize it in the console once), PAT secret missing, artifact bucket unavailable.
- `KANCLI314` / `KANCLI315` — `pipeline up` needs interaction it can't get (`--non-interactive`), or is missing config — 315 aggregates *all* missing flags into one message.
- `KANCLI316` — the manifest declares cross-repo dependencies, so CodeArtifact coordinates are required.
- `KANCLI317` — reconciling the pipeline stack with a hand-edited template failed.

## Params & secrets (098–101)

- `KANCLI098` — a `param:` reference points at an SSM parameter that doesn't exist under the stage's parameter path.
- `KANCLI099` — a `secret:NAME#key` reference names a JSON key the secret doesn't contain.
- `KANCLI100` — writing the parameter in `add param` failed.
- `KANCLI101` / `KANCLI102` — doctor's provider network / domain checks failed (degraded to warnings — doctor stays exit 0).

## Templates & licensing (320–321, 330–344)

- `KANCLI320` — this template requires the paid subscription feed (`--paid`).
- `KANCLI321` — the bundled free template pack is missing from the CLI install.
- `KANCLI330` / `KANCLI331` — the command (330) or template (331) is locked behind a feature key your license doesn't enable.
- `KANCLI332` / `KANCLI333` — license invalid / signature invalid at startup (warnings).
- `KANCLI340`–`KANCLI344` — `doctor --features` findings about edition, interceptor mode, and locked references (info / warning).

## Distribute & destination authoring (350–363, 370–381, 421–426, 510–512)

- `KANCLI350`–`KANCLI358` — `aws distribute` failures: missing stage, no distributables declared, edition / target / provider / destination problems, publish or upload failed.
- `KANCLI359` / `KANCLI360` / `KANCLI363` — `add distributable`: missing project, duplicate id, path outside the project.
- `KANCLI370`–`KANCLI372` — the configured sign / verify / package command failed.
- `KANCLI380` — recording the publish to the ledger / release feed failed.
- `KANCLI421`–`KANCLI426` — package-identity guards for CodeArtifact distribution: id collisions, unanchored or invalid ids, identity mismatch before publish.
- `KANCLI510`–`KANCLI512` — `configure distribution` received missing/invalid input, an unknown provider, or a duplicate selector without `--replace`.

## Deploy targets: ECS, static sites & rollouts (390–457)

The v2 deploy surface spans Lambda, ECS Fargate, static sites, and coupled front-end + API pairs, plus alarm-gated rollouts.

- `KANCLI390`–`KANCLI399` — target validation: mixed-target service rules, migration opt-in required, ECS entry / stage-config requirements, build-descriptor problems.
- `KANCLI400`–`KANCLI417` — ECS Fargate deploy: missing cluster / VPC / security-group / certificate / hosted-zone references, task-definition and change-set failures, steady-state timeout, image build / push / digest failures, ECS rollback preflight (pruned task-defs or deleted digests).
- `KANCLI427`–`KANCLI446` — static-site entries: invalid entry, Node toolchain missing, build failed, secret-injection refusals (secrets never enter a static bundle), certificate / zone / coupled-endpoint problems, promotion / teardown / preview-publish failures.
- `KANCLI447`–`KANCLI457` — rollouts: invalid rollout config, alarm-gate unresolved, rollout aborted by alarm, auto-rollback failed, coordinator interruptions, governance violations.
- `KANCLI381` — a path failed the traversal-safety guard (e.g. a malicious stage name).

## Bands not listed here

- `KANCLI240`–`KANCLI258` — raised by the **Kanject.Core.SqlDatabase (Aurora DSQL)** runtime, not by CLI commands; those codes are documented with the library.
- `KANCLI467`–`KANCLI501` — the `kanject packages` release-engineering surface (internal tooling for publishing Kanject's own packages).
- A handful of numbers are dormant or retired and never emitted; they keep their slots so no code is ever reused with a different meaning.

Related: [CLI Troubleshooting](https://www.kanject.com/docs/cli-troubleshooting/) for the ranked common-failure walkthroughs · [Command Map](https://www.kanject.com/docs/cli-commands/) · [Dependency Sources & Resolution](https://www.kanject.com/docs/cli-dependencies/) · [CI/CD Pipeline](https://www.kanject.com/docs/cli-pipeline/).

---
_Source: https://www.kanject.com/docs/cli-diagnostics/ · Kanject Docs_