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

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.

KANCLI566

Your AWS SSO session (or credentials derived from it) expired while the command was running. Run aws sso login and re-run.

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 / 015

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 / 199

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 / 058

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–049, 161, 660)

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

KANCLI046

Entry selection is ambiguous, unknown or incompatible; pass a compatible --entry ID.

KANCLI047

The launch profile is incompatible with HTTP or Lambda TestTool; select a compatible profile.

KANCLI048

The HTTP process exited before readiness; inspect application startup output.

KANCLI049

HTTP startup timed out; fix startup or increase --startup-timeout. The process tree is stopped.

KANCLI660

Native IDE setup/bootstrap failed before application entry. Refresh setup and check stage credentials; see Local Development for IDE-specific recovery.

KANCLI161

kanject env omitted the stage when prompting was unavailable; pass --env <stage> in automation.

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

KANCLI120–127

init argument problems: invalid --package-type / --schema, no or duplicate stages, unknown default stage, mutually-exclusive flags, bad --cwd.

KANCLI128–134

new problems: mutually-exclusive flags, bad --cwd, template pack not installed, unknown template, dotnet new failed, runtime detection failed, manifest update failed.

KANCLI135–137

update problems: mutually-exclusive flags, CLI package update failed, template pack update failed.

KANCLI138–144

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–148

add stage: bad --cwd, invalid stage name (lowercase / digits / hyphens), stage already declared, stage file already exists.

KANCLI149–160

add secret / add env / add lib / add param missing-argument errors; notably KANCLI154 — KANJECT_-prefixed env keys are reserved.

KANCLI162–166

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.

KANCLI169

kanject update installed a package whose signed provider manifests don't verify against the official key, so the install can't be trusted. Roll back with dotnet tool install -g Kanject.Cli --version <previous> and update again from the official feed. Official builds only; --no-verify skips this check, and with it a security gate.

KANCLI022 / 023

Solution-file bootstrap failed (dotnet new sln / dotnet sln add).

Plugins & providers (070–072, 170–189, 197)

KANCLI070 / 071

The manifest names an unknown (070) or empty (071) cloud provider.

KANCLI072

Installed provider plugin version doesn't match what the host requires.

KANCLI170–175

Plugin load failures: assembly load, entry point missing / duplicated, ABI mismatch, instantiation, contract not implemented.

KANCLI176–182

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 / 187

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

KANCLI189

A plugin's signed manifest is missing, doesn't verify, or doesn't match the plugin's files (a modified or extra file). Official builds skip the plugin with a warning instead of loading it; source builds don't check.

KANCLI197

Two installed plugins claim the same key.

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

KANCLI030–033

VPC validation: VPC missing, subnet or security group not in the VPC, subnets span only one AZ.

KANCLI034–038

Domain validation: certificate in the wrong region or not covering the name, hosted-zone mismatch, invalid FQDN, invalid base path.

KANCLI080–085

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–215, 583–585, 609–610)

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–108

Multi-entry template merge failures: no entries / resources / function, resource or output conflicts, multiple functions where one is expected.

KANCLI109–114

Packaging and serverless-deploy runner failures (dotnet lambda package-ci / deploy-serverless), SAM preflight warnings (111–112).

KANCLI200–203

CloudFormation deploy failed, change-set failed, deploy timeout, resource not found during the alias flip.

KANCLI209–215

Artifact-path failures: --no-build packaging, serverless base-template problems, aws template migrate preconditions, unsupported target framework.

KANCLI583–585

Native AOT entries: a function or AssemblyName that would not start the native binary (583), a machine that can't build it — no Docker, or a CPU architecture other than the function's (584), or an entry project that doesn't evaluate or restore (585). Raised before anything builds; doctor --env reports the same.

KANCLI609 / 610

A multi-entry service's templates disagree: two entries define the same Parameters, Rules, Mappings or Conditions name differently (609), or the same Globals property outside Globals.Function differently (610).

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

KANCLI087 / 088

rollback needs --env; and in a non-TTY shell, an explicit --to.

KANCLI091–095

deployments argument errors: missing stage / ref / mark args, S3 write failed, unknown action.

KANCLI116–118

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 / 420

Ledger reconciliation: live stack diverged from the active pointer (419); ledger namespace collision (420).

KANCLI463 / 464

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–318, 567–569, 608)

KANCLI096 / 097

pipeline bootstrap: template not found / required flag missing.

KANCLI310–313

pipeline up preflight: AWS credentials invalid, CodeStar connection not ready (authorize it in the console once), PAT secret missing, artifact bucket unavailable.

KANCLI314 / 315

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.

KANCLI318

The repo-wide shared pipeline config (kanject-cli/pipeline.shared.json at the git root) can't be used: --shared outside a git repository, or the file doesn't parse.

KANCLI567–569

pipeline promote refused: no rehearsal ran for this exact commit (567), the latest rehearsal didn't succeed or is still running (568 — wait for it, then promote again), or the target branch moved and is no longer a fast-forward (569).

KANCLI608

--commit on pipeline promote, pipeline status or packages release status doesn't resolve to exactly one commit: an ambiguous or unknown abbreviation, or one a branch or tag of the same name shadows. Pass the full SHA.

Params & secrets (098–101)

KANCLI098

A param: reference (or add param) was used on a stage with no parameterStore.path in its stage file. Set the path, or remove the reference.

KANCLI099

A secret:NAME#key reference names a JSON key the secret doesn't contain.

KANCLI100

add param on a stage with no parameterStore.path: the same condition as 098, raised when writing.

KANCLI101 / 102

Doctor's provider network / domain checks failed (degraded to warnings — doctor stays exit 0).

Templates & features doctor (320–321, 340–344)

KANCLI320

"You require subscription to access this": kanject test couldn't restore a paid Kanject library the template builds on (instant-messaging, file-server). Configure the subscription feed. Before 1.0.53 it meant a paid-only template.

KANCLI321

The bundled free template pack is missing from the CLI install.

KANCLI340–344

doctor --features findings about edition, interceptor mode, and locked references (info / warning).

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

KANCLI350–358

aws distribute failures: missing stage, no distributables declared, edition / target / provider / destination problems, publish or upload failed.

KANCLI359 / 360 / 363

add distributable: missing project, duplicate id, path outside the project.

KANCLI370–372

The configured sign / verify / package command failed.

KANCLI380

Recording the publish to the ledger / release feed failed.

KANCLI421–426

Package-identity guards for CodeArtifact distribution: id collisions, unanchored or invalid ids, identity mismatch before publish.

KANCLI510–512

configure distribution received missing/invalid input, an unknown provider, or a duplicate selector without --replace.

KANCLI361 / 362

doctor --features: a distributable's edition ladder (info), or a target that selects an edition not on that ladder.

KANCLI513 / 514

distribute init found no S3 targets to provision (513), or creating a bucket or applying its security settings failed — often a bucket name already taken globally (514).

KANCLI515

aws distribute received an action it doesn't recognise.

KANCLI516–519

Candidates and promotion: no <Version> to base the -rc.N on (516), the candidate feed can't be read (517), no matching candidate to promote (518), or the copy to stable failed (519).

KANCLI520–525

Onboarding: --scaffold-archive or configure distribution scaffold couldn't safely create their files (520, 525), impossible option combinations such as --offline without --dry-run (521), and doctor --features readiness advisories for version, packaging, and signing (522–524).

KANCLI526

The payload-sign command failed, so no installer was built around unsigned binaries.

KANCLI527–534

Native code signing with a typed signing block: conflicting config, readiness, macOS signing on a non-Mac host, nothing to sign, and Authenticode, timestamp, notarization, or verification failures.

KANCLI535–539

Typed packaging block: unknown provider (535), invalid block or tool pin (536), a host, RID, format, or dependency declaration the provider can't handle (537), planning failed (538), invalid provider output (539).

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

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

KANCLI390–399

Target validation: mixed-target service rules, migration opt-in required, ECS entry / stage-config requirements, build-descriptor problems.

KANCLI400–417

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–446

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–457

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

KANCLI563

A static-site entry's projectPath is a git submodule that was never initialised. Run git submodule update --init <path>.

Packages: verify, publish & release (467–508, 540–565, 570, 587–603)

Raised by kanject packages and kanject aws packages. The Publish .NET packages page covers the ones a new setup hits first.

KANCLI467–469

No packaging/kanject.packages.json (467), the policy fails strict validation (468), or the project graph can't be loaded (469).

KANCLI470–480

packages verify failures: a public package with no project or not packable, a public package depending on a non-public first-party package, a version floor above what the repo builds, a denied or unclassified package, source/symbol or license policy violations, duplicate package IDs.

KANCLI481 / 482

The public-only restore smoke (481) or template smoke (482) failed.

KANCLI483–487

packages publish: unreadable .nupkg identity, live push without --ci / --confirm, a feed that can't be resolved, push failed, nothing to push.

KANCLI488 / 490 / 502

doctor advisories: an expired CodeArtifact token, a stale checked-in schema copy (packages init --refresh-schema), an AWS credential chain that can't sign in.

KANCLI489 / 491 / 492

A stable version sent to a public candidate route, the packed set doesn't match the expected package IDs, next-rc can't read the candidate feed.

KANCLI493–499

Release plans and publication: packed files or policy changed since the plan, a version already on a feed with different contents (495), a journal from a different plan, a candidate version already taken (497), a feed that failed preflight, publication stopped partway (499).

KANCLI500 / 501

A weakened public rule without a documented exception (500), or a candidate that can't be installed from the candidate feed (501).

KANCLI503–508

versions --strict found a package that needs a new version, an invalid release profile, a dependency cycle in the release set, a candidate consumer that failed to build (506), invalid composite-consumer policy, or smoke fixture init couldn't add its files.

KANCLI540–552

bump preview / plan / apply: invalid input, a package whose build isn't reproducible (two clean builds of the same commit differ), a version or pin that can't be safely edited, planning or restore-integrity failures, a version conflict with the feed, a changed plan binding at apply, path escapes, cache or resource-limit problems.

KANCLI553–555

candidate materialize: invalid options, a dependency range that can't be safely rewritten, or a candidate that differs from its stable package.

KANCLI556–562

release prepare / stage, release.pipeline.json, and the hosted pipeline: invalid configuration, preparation or bundle failures, staging failed, a size limit exceeded, or the release pipeline's plan (560) or apply (561) failed or stopped partway (re-run to resume the change set).

KANCLI565

Nothing to release: every package already matches what's published. bump plan fails with it; packages release treats an empty wave as success and completes without an approval.

KANCLI570

A package the plan left at its published version no longer matches it. Add it to the release with --include.

KANCLI587 / 588

Warning: files in the checkout differ from what git would check out, so planning used git's version (587); or git couldn't list the files to plan from (588).

KANCLI590–592

aws packages release pipeline: the Build buildspec breaks the pipeline contract (590), the Kanject.Cli tool pin can't be the trusted publisher (591), or the deployed stack wasn't rendered by the CLI (592; use --adopt).

KANCLI589 / 593 / 598 / 599

aws packages release pipeline up --apply guards: no confirmed plan (run up --plan --out <FILE>, review it, apply with --plan-file), the template couldn't be uploaded and read back unchanged, the change set would replace or remove a CodeBuild project, bucket, or the pipeline (--allow-replace), or an execution is in flight in an affected stage (--supersede-in-flight; Sign and Publish always block).

KANCLI594–597

packages release: the working tree isn't ready (uncommitted changes, detached HEAD), the hosted rehearsal failed, the wait timed out (nothing is undone), or the pipeline failed after promotion.

KANCLI600–603

Release scopes: an invalid --package or packaging/release.scope.json (600), a scoped wave that would break a consumer it leaves behind (601), scope carry can't find fully published bytes for a package outside the scope (602), or an outside package's source changed without a release (603).

KANCLI604 / 606

Release intent: a declaration or packaging/release.intent.json is malformed, --part asks for less than a declaration requires, or a hosted bump plan --intent-file found declarations no release commit resolved (604); or packages release was run from a branch that doesn't contain the tracked branch's tip (606 — fetch and rebase first). 605 and 607 are reserved.

Public build inputs and CLI guidance (661–664)

KANCLI661

Build-input declaration, stage selection, public source, or property validation failed; fix the named input and select an explicit stage.

KANCLI662

Packaged assembly metadata is absent, unsupported, or differs from the selected public build inputs; embed and verify the declared values before release.

KANCLI663

The requested shell is unsupported; select bash, zsh, or powershell.

KANCLI664

Workflow configuration cannot be read or its local metadata is incomplete or unsafe; repair the named configuration at the selected root.

Managed Lambda HTTP access (670–681)

KANCLI670

HTTP configuration contains unsupported values; fix the named field.

KANCLI671

HTTP setup is incomplete; configure the entry and required verification path.

KANCLI672

HTTP function identity is missing or ambiguous; select the exact logical resource.

KANCLI673

Application hosting does not match the HTTP access contract; repair startup and serialization.

KANCLI674

The HTTP capability combination is unavailable; choose a supported method, host and auth policy.

KANCLI675

HTTP resources or source are externally owned; preserve them or prepare an explicit migration.

KANCLI676

The HTTP stage/domain topology is incompatible; remove the conflicting configuration.

KANCLI677

The managed HTTP integration does not invoke the recorded live alias; repair its stack.

KANCLI678

HTTP reconciliation failed; inspect its recorded phase and rerun deployment.

KANCLI679

A required endpoint probe failed; repair the declared safe endpoint or its credentials and redeploy.

KANCLI680

HTTP migration, lease recovery or a stale-operation repair is required before deployment.

KANCLI681

HTTP state could not be restored or persisted; inspect the recorded handles before retrying.

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.
• KANCLI220–KANCLI233 are reserved for a kanject verify command that has not shipped, and KANCLI571–KANCLI582 and KANCLI586 are held for work in progress.
• Retired codes are never emitted but keep their numbers so none is reused: KANCLI188 and KANCLI330–KANCLI333 (licence gating, removed), KANCLI216 (deploy env staging, replaced in 1.0.36), and KANCLI458.

Related: CLI Troubleshooting for the ranked common-failure walkthroughs · Command Map · Dependency Sources & Resolution · CI/CD Pipeline.