CLI Troubleshooting

Most CLI failures are designed to be diagnosable from kanject doctor, command exit codes, and KANCLI### diagnostic codes.

kanject: command not found

# macOS / Linux (zsh)zsh: command not found: kanject​# Windows (PowerShell)kanject : The term 'kanject' is not recognized as the name of a cmdlet,function, script file, or operable program.

The install almost certainly worked: the .NET global-tools folder just isn't on your PATH, and doctor can't tell you so because the command itself won't run. dotnet tool list --global shows kanject.cli if the tool is installed. The two-command fix for each OS is under Installation → Common installation issues.

Start with doctor

kanject doctorkanject doctor --env prod

Run it inside a service. Without --env, doctor checks the .NET SDK, the global-tools PATH, the manifest and lockfile, and the Lambda tooling; it calls AWS only to check your sign-in when the repository's packaging policy uses a CodeArtifact feed. With --env, it also checks that stage's configuration and AWS readiness. Outside a project it reports kanject-cli/manifest.json not found (KANCLI002). Only errors set exit code 1; warnings keep it 0.

Gate CI with doctor --json

--json drops the table and prints a stable schemaVersion: 1 report — exitCode, a summary of counts, and a results[] array of { severity, code, message, hint } — so a pipeline step can stop before spending a build:

# Fail the job on any error-severity finding, before the build spends a centkanject doctor --json --env stage \  | jq -e '.results | map(select(.severity == "error")) | length == 0'

Common diagnostics

Codes never renumber, so they're the thing to search for or paste into a ticket. The three you'll meet first are below; the diagnostic-code reference indexes every code the CLI can emit.

Local API not visible or missing SignIn:CodePepper

A missing/short CodePepper means the process did not receive its stage secret. Use kanject test --entry api --http --env dev --pull-env --debug for CLI launch-and-attach. For native Debug/F5 in CLI 1.0.67+, run explicit setup with --pull-env, then select the generated profile in your IDE. Full Rider, VS Code and Visual Studio steps include credentials, refresh and breakpoint checks.

A root 404 can be correct: an API does not necessarily serve a page, and /health exists only if mapped. Wait for Ready during CLI runs and request a known endpoint. KANCLI046/047 mean entry/profile selection problems; KANCLI048/049 mean early exit/timeout. KANCLI660 means native bootstrap failed before application code: refresh IDE setup and check the selected stage’s AWS login.

Failure patterns

• Manifest/stage mismatch — every stage listed in the manifest needs a matching stage file.
• AWS profile/region issue — confirm the profile exists locally and in CI.
• Artifact bucket missing — the CLI never creates it; create the bucket, or let your team's IaC provision it, before the first deploy.
• Cross-repo dependency issue — check git access, pinned refs, and manifest.lock.json drift.