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

# Troubleshoot Scan

> Resolve githits-scan authentication, file selection, upload, network, and saved-report errors.

When a Scan command fails, check its message on stderr and its [exit code](https://docs.githits.com/scan/commands.md#exit-codes). Run `githits-scan --version` to confirm which version you're using. This guide covers **Alpha** version 0.3.0.

## Authentication and account access

| Symptom | What to do |
| - | - |
| Missing or rejected token (exit 2) | Set `GITHITS_API_TOKEN` in the process running Scan. Create or replace the token in [token settings](https://app.githits.com/settings/tokens). Scan does not read the `githits` CLI's stored login. Never paste the token into a report. |
| Access denied or terms required (exit 2) | Sign in at [app.githits.com](https://app.githits.com) and follow the message's instructions for account access, feature access, or terms. Retrying cannot grant access. |

## File selection and uploads

| Symptom | What to do |
| - | - |
| Inventory drift or nothing selected (exit 1) | Run `detect` and review the configuration, ignore rules, and scan root. Save an updated inventory after reviewing it. See [inventory drift](https://docs.githits.com/scan/configuration.md#inventory-drift). |
| Upload too large (exit 2) | Scan a smaller root or explicitly exclude unrelated projects. Workspace member manifests count toward the limits too. See [file selection](https://docs.githits.com/scan/configuration.md#exclusions-and-discovery) and [upload limits](https://docs.githits.com/api/lockfile-analysis.md#prepare-files). |
| Unsupported file or `UNUSABLE_MANIFEST` (exit 2 for rejected input) | Check the [supported package files](https://docs.githits.com/scan/configuration.md#supported-package-files), file contents, and paths named in the diagnostic. Scan does not convert formats. One unusable selected file rejects the whole upload. Exclude a file if you intend to leave it out of the analysis. |
| Permission denied or unreadable file/output (usually exit 3) | Check that Scan can read the scan root and selected files and write to the output directory. A missing input or configuration exits 2 instead. Fix file access or selection rather than running Scan as administrator. |

## Network and service errors

| Symptom | What to do |
| - | - |
| Proxy, TLS, timeout, or connection failure (exit 3) | Check connectivity and proxy settings. Proxies must allow authenticated HTTPS and streaming progress responses. Scan refuses redirects. Do not disable TLS checks. |
| Rate limit or service failure (exit 3) | Keep the request ID and wait for `Retry-After` when supplied before retrying. Rerunning submits a new job and can consume quota again. Scan does not automatically retry submission or result requests. |

Scan uses these timeouts:

| Operation | Allowance |
| - | - |
| Establish a connection | 15 seconds |
| Receive submission/result headers or read each part of the body | 210 seconds |
| Read progress events | 60 seconds |

An established progress stream can reconnect without resubmitting the analysis job.

## Saved reports and policy

If an offline command rejects a saved file, check that you're using the [matching replay input](https://docs.githits.com/scan/commands.md#offline-replay):

| Command | Required input |
| - | - |
| `audit --from-analysis FILE` | An audit analysis saved with `--save-analysis` |
| `license report --from-report FILE` | License report JSON saved with `license report --json` |
| `license check --sbom FILE` | A CycloneDX JSON SBOM |

Compact audit JSON and license policy verdicts are not replay inputs.

Offline `license check` still needs a [`[licenses]` policy](https://docs.githits.com/scan/configuration#license-policy). An informational `license report` can exit 0 with unknown licenses or incomplete information. That exit code means the report was produced; it does not mean a policy check passed.

## Report a problem

Include the following in a [bug report](https://github.com/githits-com/githits-scan/issues):

* Scan version and OS.
* The command and exit code.
* Stderr with credentials and sensitive values removed.

Inventory and reports can reveal private paths and package names. Review attachments before sharing, and never include credentials. Report security concerns privately using [Scan's security policy](https://github.com/githits-com/githits-scan/security/policy).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.