# Troubleshooting

> Exit codes, coverage warnings, limits and suppressions.

Source: https://keryn.dev/docs/guides/troubleshooting/

## Goal

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

## Before you start

- 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.

## 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

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`

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:

```sh
keryn scan . --max-files 1
```

```text
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"

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](https://keryn.dev/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`

That is the [rescan cache](https://keryn.dev/docs/guides/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

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"

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

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](https://keryn.dev/docs/cloud/domains/) whose proof is still in place, or a [rate limit](https://keryn.dev/docs/cloud/data-and-limits/#limits). A target that answers too slowly stops at 45 seconds.

## 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 a `suppress:` entry that carries a reason and an expiry: [suppressions](https://keryn.dev/docs/guides/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

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

`keryn explain <rule id>` prints the rule's message, severity, confidence, edge and remediation offline: [explain and docs](https://keryn.dev/docs/guides/explain-and-docs/). `keryn docs exit-codes` prints the table above.

## Get help

If the steps above do not resolve the problem, use the [support route](https://keryn.dev/security/#everything-else). 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

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.

## Next

- Fix noise at the source: [suppressions](https://keryn.dev/docs/guides/suppressions/) and [policies](https://keryn.dev/docs/guides/policies/).
- Read a finding properly: [read an attack chain](https://keryn.dev/docs/guides/attack-chain/).
