Skip to content

    Type a page, a command such as keryn scan, or a rule id.

    Troubleshooting

    View as Markdown

    Find the cause of a scan that fails, warns or says less than you expected, using what Keryn already printed.

    • The exact command, its exit code and the last lines of its output. The coverage: and result: lines say most of what you need.
    • keryn version --json, for any report you send.

    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.

    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 scan stops, instead of reading part of a tree, when the tree is bigger than the limits. It exits 4 and says which limit:

    Terminal window
    keryn scan . --max-files 1
    keryn: internal error: LIMIT_EXCEEDED: source tree exceeds maxFiles/maxTotalBytes

    Raise --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.app without 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.

    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.

    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.

    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.

    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.

    • 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 a suppress: 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).

    By default Keryn skips symlinks (--symlinks skip). follow-confined follows them only when they stay inside the scanned directory; error fails on any.

    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.

    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.

    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.