Error Codes & Troubleshooting

Written and maintained by Hendrik Schneider · Last reviewed 2026-08-18 · How we check this

A consolidated reference for the error codes the CLI and engine surface, plus the most common causes and the fix path for each. When in doubt: set global.logLevel to DEBUG in the config file and re-run; the log will reference the same codes and point to the failing component.

CLI Exit Codes

Every Korthex CLI command returns a stable exit code so that scripts and CI gates can react reliably. The numbers are banded, and the bands are the part worth branching on when a specific code is not: 0-9 core outcomes, 10-19 quality gates, 20-29 baseline and contract, 30-39 policy, 40-49 configuration, 50-59 integrity, 60-69 infrastructure. Bands are sparse on purpose so a new class never reuses an old number.

Exit code	Meaning	When you see it
0	Clean	Completed, and no threshold in play was crossed.
1	Findings present	The run produced findings. Expected, not an error. Note that this number is deliberately avoided by korthex check, because it already carries more than one meaning.
2	Generic failure	The catch-all for a failure with no more specific class.
3	License required	The operation needs a tier the active license does not grant.
4	Usage error	Unknown flag, missing required option, invalid value.
5	Cancelled	User-initiated cancel, or the native timeout/cancel class.
10	Quality gate failed	A gate fired on a measured value: accuracy below its threshold, coverage below target. The measurement itself succeeded.
20	Baseline mismatch	A baseline or contract comparison did not match.
30	Policy violation	A rule the operator wrote said no.
31	Policy input unreadable	The policy engine could not read the report it was asked to judge. Distinct from 30 on purpose: "I never looked at your report" is not "I looked and found violations".
32	Policy not loaded	Evaluate or enforce was reached with no policy loaded at all.
33	Check threshold exceeded	At least one finding at or above the --fail-on severity. Distinct from 30: 30 is a written rule, 33 is the ceiling passed on the command line.
34	CI token rejected	The backend definitively refused KORTHEX_CI_TOKEN . A backend that could not be reached is not this code: that outcome is disclosed and the run continues on its local verdict.
35	Check scan timeout	The scan exceeded the policy-declared wall clock. Distinct from 5, which a user-initiated abort also produces.
40	Configuration invalid	The scan or CI configuration was missing, malformed or rejected.
41	Policy source invalid	A policy file was found but is not a usable policy: empty, unparsable, not a JSON object, or oversized. It never governed anything, and it never falls through to the next tier.
50	Decryption failed	The report could not be decrypted or failed its integrity check.
60	Infrastructure error	An outage on the service side.
61	Backend unavailable	The backend could not be reached.

Common Issues

Symptom	Likely cause	Resolution
"License missing" on first run	Activation step not completed.	Run korthex license activate KX-XXXX-XXXX-XXXX-XXXX or set KORTHEX_LICENSE.
"License server unreachable"	Offline machine without offline-activation token.	Use the challenge/redeem flow under License Management → Offline Activation.
Scan finishes with 0 findings on a real codebase	Path matched .korthexignore or .gitignore aggressively; or all detection toggles off.	korthex config show; check the ignore rules and detection.* toggles.
Scan is unexpectedly slow on a repo that was fast yesterday	The cache was invalidated, so the run fell back to a full analysis. A Korthex upgrade does this by design: the engine binary is part of the cache fingerprint, so the first scan after an update is cold.	Expected once per upgrade - the next scan is incremental again. To confirm the reason rather than guess it, read delta_scan_fallback in the report: it names why the snapshot was not used.
High false-positive count	Context Engine disabled, or test fixtures not excluded.	Re-enable context (default); add test/ paths to .korthexignore.
"Cannot parse .kxr"	Wrong tool version reading a newer report.	Update Korthex on the reading side. .kxr forward-compatibility is best-effort but not guaranteed across major versions.
"Schema mismatch"	Input file from a newer Korthex than the current binary.	Update Korthex, or re-emit the file from a version-compatible source. There is no exit code reserved for this class; it surfaces as a generic failure.
IDE plugin shows no findings	CLI path misconfigured or CLI not on PATH.	Settings → Tools → Korthex → set the CLI Path explicitly; restart IDE.
Korthex Remote: "License mismatch"	Phone paired with a desktop on a different license seat.	Revoke from desktop; re-pair with the correct desktop. Mobile auto-routes back to login.
Mesh-Relay: "SPKI pin file not found" (fail-closed)	Pin file missing or path misconfigured in relay_config.json.	Either provide the pin file or remove Mesh-Relay configuration entirely.
Exploit Engine: "GATED"	Feature gate is closed (default state).	Open the gate via the Dashboard toggle or the host SDK; acknowledge ToS.
Build: "out of memory" on large monorepo	Too many analyzers holding memory at once.	Lower global.maxThreads in the config file. Neither parallelism nor engine selection has a command-line switch; to run the light engines first, turn the heavy ones off under engines.subEngines and re-run with them back on.

Logs & Diagnostics

Log Levels The level is a configuration key, global.logLevel , read from the file you pass to --config . There is no --log-level switch. The value is matched case-insensitively and the default is INFO . { "scanPaths": ["."], "global": { "logLevel": "DEBUG" } } No environment variable sets the log level. KORTHEX_LOG_LEVEL and per-engine variants of it do not exist anywhere in the product, and neither does a --log-file switch. What is true is the fact those invented variables were reaching for: every engine carries its own logger instance, so a level set for one does not propagate to the others. Today only the scanner reads global.logLevel and applies it to its own logger. Log Locations Every component writes under one per-user root, and each engine gets its own subdirectory below it with a session-stamped file name: <root>/logs/engines/<EngineName>/ . Crash Reports On a crash, Korthex emits a minidump ( .dmp ) plus a JSON sidecar to the configured crash directory (default: alongside the log directory under crashes/ ). The minidump excludes source-code memory pages via the built-in redactor; the JSON sidecar contains environment metadata only. When opening a support ticket, attach: the crash sidecar JSON, the last log file from the same session, and the command line that triggered the issue. Do not attach minidumps over public channels - they may contain residual heap data; ship them through the support portal upload only.

Value	What it does
OFF	Suppresses every log call.
ERROR	Failures only. The quietest useful setting for CI.
WARN	Adds recoverable engine-internal notices.
INFO	The default. Adds phase transitions and the durations that the Context passes and the enrichment phase report.
DEBUG	Verbose diagnostic detail. This is the level to attach to a bug report.
TRACE	Accepted, but it is an alias: the logger maps it onto DEBUG and there is no finer level behind it.

Platform	Root
Windows	%APPDATA%/Korthex/
macOS	~/Library/Application Support/Korthex/
Linux	$XDG_CONFIG_HOME/Korthex/
Linux, no XDG_CONFIG_HOME	~/.config/Korthex/

Where to Get Help

Channel	Best for	Response time
Documentation search (this site)	Quick reference, syntax, formats.	Instant
Community Discord / Slack	Usage questions, sanity checks, recipes.	Hours (community-driven)
Email support (Community+)	Account-specific issues, bug reports.	Business day
Chat support (Business+)	Faster triage, demo questions.	Same business day
Dedicated CSM (Enterprise)	Roadmap input, escalations, deployment review.	SLA-bound