> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> The stable, machine-readable failure code and pipeline stage taxonomy Crypto Finder emits with --error-format json, for CI parsers and downstream tooling.

Crypto Finder reports terminal failures with a **stable machine-readable code and pipeline stage**. Codes are an external contract consumed by CI parsers and downstream tooling — shipped codes are never renamed.

## Consuming Errors in CI

With `--error-format json`, any failure is emitted to **stderr** as a single JSON payload, and the process exits with code `1`:

```bash theme={null}
crypto-finder scan --error-format json /path/to/code 2> error.json
```

```json theme={null}
{
  "code": "scanner_timeout",
  "stage": "scan",
  "retryable": false,
  "message": "scan timed out after 10m: ...",
  "details": { "timeout": "10m" },
  "cause": "context deadline exceeded"
}
```

| Field                 | Meaning                                                                     |
| --------------------- | --------------------------------------------------------------------------- |
| `code`                | Stable failure identifier (table below). Parse on this, never on `message`. |
| `stage`               | Pipeline stage that produced the failure (table below).                     |
| `retryable`           | Whether retrying the same invocation may succeed.                           |
| `message`             | Human-readable description (free text, may change between releases).        |
| `details`             | Optional structured key/value context (e.g. the offending flag value).      |
| `cause` / `raw_error` | Underlying error text, when available.                                      |

Errors that were never classified surface as `code: "unknown_error"`, `stage: "unknown"`.

<Note>
  `--error-format json` also disables log output and colors so stderr
  carries only the payload.
</Note>

## Stages

| Stage        | Pipeline phase                                        |
| ------------ | ----------------------------------------------------- |
| `input`      | CLI argument/flag validation                          |
| `config`     | Configuration, cache, and Java runtime initialization |
| `rules`      | Rule source loading                                   |
| `scan`       | Language detection and scanner execution              |
| `dependency` | Dependency resolution and dependency scanning         |
| `callgraph`  | Call graph construction                               |
| `export`     | Call graph / graph fragment export                    |
| `output`     | Findings report formatting and writing                |
| `policy`     | Post-scan policy decisions (`--fail-on-findings`)     |
| `unknown`    | Unclassified                                          |

## Codes

The stage column shows the typical stage; the stage is assigned where the error becomes terminal, so a code can occasionally surface under a different stage.

| Code                            | Typical stage | Meaning                                  | Typical cause                                                                                                 |
| ------------------------------- | ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `unknown_error`                 | `unknown`     | Unclassified failure                     | A plain error escaped without boundary wrapping                                                               |
| `invalid_arguments`             | `input`       | Flag/argument validation failed          | Bad flag value, missing required flag, unknown backend/format                                                 |
| `invalid_timeout`               | `input`       | Unparseable duration                     | `--timeout` / `--max-stale-age` not in `10m` / `1h` / `30d` / `2w` form                                       |
| `config_initialization_failed`  | `config`      | Configuration could not be initialized   | Unreadable/invalid config file or environment                                                                 |
| `java_runtime_config_invalid`   | `config`      | Java runtime selection invalid           | Bad `--java-jdk-major` / malformed `--java-jdk-home <major>=<path>`                                           |
| `cache_initialization_failed`   | `config`      | Rules or findings cache setup failed     | Cache dir not writable; `--findings-cache=postgres` without `SCANOSS_FINDINGS_CACHE_DSN`, pool/schema failure |
| `rules_load_failed`             | `rules`       | No usable rule source                    | `--no-remote-rules` without `--rules`/`--rules-dir`; remote ruleset fetch failed with no cache                |
| `scanner_unavailable`           | `scan`        | Requested scanner not found              | `opengrep`/`semgrep` binary not installed or not on `PATH`                                                    |
| `scanner_initialization_failed` | `scan`        | Scanner setup failed                     | Scanner present but could not be prepared for the run                                                         |
| `scanner_execution_failed`      | `scan`        | Scanner process failed                   | Non-zero scanner exit, crash, or invalid rule files                                                           |
| `scanner_timeout`               | `scan`        | Scan exceeded `--timeout`                | Target too large for the configured timeout                                                                   |
| `scanner_canceled`              | `scan`        | Scan canceled                            | Context canceled (e.g. SIGINT)                                                                                |
| `scanner_output_parse_failed`   | `scan`        | Scanner output unreadable                | Scanner emitted output the parser could not decode                                                            |
| `language_detection_failed`     | `scan`        | Language detection failed                | Unreadable target tree                                                                                        |
| `dependency_resolution_failed`  | `dependency`  | Dependency resolution/scan failed        | Missing toolchain, unresolvable manifest, dep scan error                                                      |
| `java_build_tool_unknown`       | `dependency`  | Java build tool not detected             | No `pom.xml` / Gradle build files found                                                                       |
| `java_build_tool_ambiguous`     | `dependency`  | Multiple Java build tools detected       | Both Maven and Gradle present without a clear winner                                                          |
| `gradle_tool_missing`           | `dependency`  | Gradle unavailable                       | No usable `gradle` / wrapper for dependency export                                                            |
| `gradle_export_failed`          | `dependency`  | Gradle dependency export failed          | Gradle invocation failed or produced unusable output                                                          |
| `gradle_java_incompatible`      | `dependency`  | Gradle/JDK mismatch                      | Selected JDK major incompatible with the project's Gradle                                                     |
| `callgraph_build_failed`        | `callgraph`   | Call graph construction failed           | Unsupported ecosystem for export, parse failure                                                               |
| `callgraph_export_failed`       | `export`      | Export write failed                      | `--export-callgraph` / `--export-graph-fragment` destination not writable, serialization failure              |
| `output_writer_unavailable`     | `output`      | No writer for the requested format       | Unsupported `--format` value reaching the writer factory                                                      |
| `output_write_failed`           | `output`      | Report write failed                      | Output path not writable, disk full                                                                           |
| `findings_detected`             | `policy`      | Findings found with `--fail-on-findings` | Expected CI gate behavior, not an error in the tool                                                           |

## Related Documentation

* [Output Formats](output-formats) — the interim JSON, callgraph, and graph fragment schemas