Troubleshooting
Find the cause of a scan that fails, warns or says less than you expected, using what Keryn already printed.
Before you start
Section titled “Before you start”- The exact command, its exit code and the last lines of its output. The
coverage:andresult:lines say most of what you need. keryn version --json, for any report you send.
The scan exits with 3
Section titled “The scan exits with 3”Coverage is incomplete: some rules could not run (unsupported or partial for a language), or timed out. The console and every output list which. Either accept it for this run with --allow-incomplete, or narrow the rules with --rules or --exclude. Keryn reports this instead of passing silently.
The scan exits with 4
Section titled “The scan exits with 4”An internal error or a timeout. Raise --timeout <seconds>, or the size limits (--max-file-size, --max-files, --max-total-size). Report it with the output of keryn version --json.
A large repository: LIMIT_EXCEEDED
Section titled “A large repository: LIMIT_EXCEEDED”A scan stops, instead of reading part of a tree, when the tree is bigger than the limits. It exits 4 and says which limit:
keryn scan . --max-files 1keryn: internal error: LIMIT_EXCEEDED: source tree exceeds maxFiles/maxTotalBytesRaise --max-files and --max-total-size to fit the repository, or scan the part you care about (keryn scan services/api, or --exclude for generated and vendored folders). --max-file-size is different: a file over it is skipped, not an error (lockfiles over it are still read for dependencies).
Keryn Web says “GitHub rate limit hit”
Section titled “Keryn Web says “GitHub rate limit hit””Keryn Web reads a public repository from GitHub without an account, and GitHub allows an anonymous client only a small number of requests an hour, shared by everyone on your network. Keryn Web tells you before it runs out (“Only N anonymous GitHub requests are left until the time shown”) and when it has.
- Use public archive. The button on that notice switches to the fast archive: the repository’s source streams through
api.keryn.appwithout being stored, and the scan needs almost no GitHub calls. It works for public repositories only; see privacy for what that sends. - Add a GitHub token in Settings. A token raises the limit and is the way to read private repositories. You choose whether the browser remembers it.
- Wait. The notice shows when the limit resets; a queued scan of several repositories waits for it by itself and says so (“waiting for the rate limit until the time shown”).
- Scanning a whole organization lists its repositories first, which costs calls. When the plan says it needs more calls than you have, paste the repository links instead and choose public archives, or add a token.
A scan of a local folder or file uses no GitHub calls at all.
It was fast, and printed unchanged since
Section titled “It was fast, and printed unchanged since”That is the rescan cache: the tree, rules and settings are identical to an earlier scan, so its report was returned. --no-cache or KERYN_NO_CACHE=1 scans again; keryn cache clear empties the cache.
Files I expected were not scanned
Section titled “Files I expected were not scanned”The coverage line says N earlier Keryn output file(s) skipped for files Keryn recognises as its own earlier outputs (SARIF, AI-BOM, result JSON, bundles), and counts files left out because .gitignore or .git/info/exclude lists them. --no-ignore scans the ignored files too. Anything under exclude: in .keryn.yml is skipped by your own choice.
Keryn Web says “Deep did not run”
Section titled “Keryn Web says “Deep did not run””The results then have pattern-level findings (proof 1 and 2) and no cross-file proof, and the message gives the reason: the engine or vault failed to load, the tab ran out of memory, or the browser blocked the nested worker. Reload, try a smaller folder or a current Chrome, Edge or Firefox, or use the CLI for the proof. A result without that message and without any proof-3 finding means no cross-file path was found.
Keryn Cloud refuses a scan
Section titled “Keryn Cloud refuses a scan”The message names the reason: an IP address instead of a host name, a private address, a port other than 80 or 443 on a domain you have not verified, active port checks without a verified domain whose proof is still in place, or a rate limit. A target that answers too slowly stops at 45 seconds.
Too many findings
Section titled “Too many findings”- Gate on errors only (
--fail-on error, the default) and on high-confidence rules only (--gate-confidence P1, the default). - Gate on what a change adds:
--base origin/main. - Exclude generated or vendored code in
.keryn.yml(exclude:). - Suppress one finding with a
nosemgrep: <rule id>comment on its line, or with asuppress:entry that carries a reason and an expiry: suppressions. - Waive a policy rule in the policy file (
waivers:with the rule, a reason and an expiry date, optionally limited to one component).
Symbolic links
Section titled “Symbolic links”By default Keryn skips symlinks (--symlinks skip). follow-confined follows them only when they stay inside the scanned directory; error fails on any.
What a finding means
Section titled “What a finding means”keryn explain <rule id> prints the rule’s message, severity, confidence, edge and remediation offline: explain and docs. keryn docs exit-codes prints the table above.
Get help
Section titled “Get help”If the steps above do not resolve the problem, use the support route. Include your Keryn version, the command or web workflow, the exit code and the coverage or status line. Remove credentials and private paths or source code before sharing.
What you just proved
Section titled “What you just proved”Every non-zero exit has a stated cause, and Keryn prints the cause rather than passing silently: incomplete coverage is exit 3, an internal error is exit 4, an expired suppression is a failure with its entry named. If a case is not on this page, the coverage: and result: lines are the place to start.
- Fix noise at the source: suppressions and policies.
- Read a finding properly: read an attack chain.