Troubleshoot Scan

When a Scan command fails, check its message on stderr and its exit code. 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. 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 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.
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 and upload limits.
Unsupported file or `UNUSABLE_MANIFEST` (exit 2 for rejected input)	Check the 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:

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

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.

Get Started

Agent tools

CLI

Scan

Guides

Troubleshoot Scan

Authentication and account access

File selection and uploads

Network and service errors

Saved reports and policy

Report a problem

​Authentication and account access

​File selection and uploads

​Network and service errors

​Saved reports and policy

​Report a problem

Authentication and account access

File selection and uploads

Network and service errors

Saved reports and policy

Report a problem