CLI Troubleshooting

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

kanject: command not found

The single most common failure — and the one kanject doctor can't catch, because if the command itself won't resolve you can't run doctor to be told why. What it looks like:

# 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 cause is almost always PATH: the .NET global-tools directory isn't on it. It shows up most often right after dotnet tool install/update, which prints the export PATH=… lines but doesn't apply them — so running kanject in that same shell, before adding them and reloading, fails.

The fix — pick your OS:

# 1 — fix the window you're in right now (session only)$env:Path += ";$env:USERPROFILE\.dotnet\tools"​# 2 — persist for every future window (writes the User PATH only)[Environment]::SetEnvironmentVariable(  "Path",  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:USERPROFILE\.dotnet\tools",  "User")​kanject --version    # now resolves

# .NET installs the shim under ~/.dotnet/tools — put that dir on PATH:echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.zprofilesource ~/.zprofile   # or just open a new terminal​kanject --version    # now resolves

# .NET installs the shim under ~/.dotnet/tools — put that dir on PATH:echo 'export PATH="$HOME/.dotnet/tools:$PATH"' >> ~/.bashrcsource ~/.bashrc     # or just open a new terminal​kanject --version    # now resolves

Start with doctor

kanject doctorkanject doctor --env prod

Without --env, doctor checks the foundations — entirely offline. With --env, it also checks stage-specific assumptions such as manifest/stage shape and provider readiness. Only errors flip the exit code to 1; warnings keep it 0.

Gate CI with doctor --json

--json suppresses all human decoration and emits a stable schemaVersion: 1 envelope — exitCode, a summary of counts, and a results[] array of { severity, code, message, hint } — so a pipeline step can gate on it 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 are stable — they never renumber — so they're the thing to search for or paste into a ticket. The three you'll meet first; the diagnostic-code reference indexes every code the CLI can emit.

Inspect env safely

kanject env --env devkanject env --env dev --show-values

kanject env masks resolved values by default. Use --show-values only in a local debugging terminal, never in CI logs.

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 — create the bucket or let your team IaC provision it before deploy.
• Cross-repo dependency issue — check git access, pinned refs, and manifest.lock.json drift.