KANCLI Diagnostic Codes

View .md

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")'

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.

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.

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 for the ranked common-failure walkthroughs · Command Map · Dependency Sources & Resolution · CI/CD Pipeline.

Was this page helpful?