Troubleshooting code references

Before you start

• Open the log of the last CI run, and the flag in FluxGate.

The job cannot download the CLI

The job stops with fluxgate: cannot download .../fluxgate-v2.0.1-linux-x86_64.tar.gz or its SHA256SUMS, after a curl: (22) The requested URL returned error: ... line. Read the status code in that line:

• 404: FLUXGATE_VERSION names no release. It must be one that exists, such as v2.0.1, with the v.
• 403: the network in front of flux.forgeopslabs.com answered with a bot check ("Just a moment...") instead of the file. Some cloud CI networks meet it. Keep a copy of the release archives and SHA256SUMS on a server your runners can reach, and set FLUXGATE_DOWNLOAD_BASE to that folder.

The CLI is built for Linux x86_64 and arm64 and macOS on Apple silicon; other runners stop with no CLI build for .... A job that stops with ... is not listed in SHA256SUMS downloaded a checksum file of another release: check that FLUXGATE_DOWNLOAD_BASE ends in the same version.

The upload was skipped

The job log shows code-refs upload skipped: ... (license_required). The install has no Business or Enterprise license. The job still passes. References uploaded before stay readable.

The log shows license_read_only instead: the license is read-only, for example after it expired. Renew it; the next push uploads again.

The scan was refused with 403

• The token lacks Code references write. Create a token with Code references write and Evaluate for the same system client.
• The token belongs to another team. The scanner uploads to the token's team.

A corrected setting comes back

You changed the default branch or the link template, and the next CI run changed it back. Edit it in Settings, Code references: an edit there pins the settings, so uploads keep them. Use CI values hands them back to CI.

A deleted branch is still listed

On GitLab, no pipeline runs when a branch is deleted. Run fluxgate code-refs prune --branch <name>, or wait: branch scans without an upload for 30 days are deleted. The log line refusing to prune the default branch means the branch is the default branch; delete the whole repository in the settings instead.

The cleanup-issues job opens no issue

• The cleanup report has no flag with Remove code, Archived but referenced or Plan removal: there is nothing to remove.
• Each flag already has an open issue titled FluxGate: remove flag <key>.
• On GitHub, FLUXGATE_CLEANUP_ISSUES is not true, or the run was a push.
• On GitLab, the log says set FLUXGATE_GITLAB_ISSUE_TOKEN: add a project access token with the api scope.

The scan cannot list flag keys

The token lacks Evaluate. Add it to the token's scopes.

The upload is too large

The answer is 413 payload_too_large. Skip generated code with --exclude, or send fewer context lines.

The scanner cannot tell the repository

The log says cannot tell the repository: pass --repo. The checkout has no remote and no CI variables. Run the scan with --repo github.com/acme/shop:

fluxgate code-refs scan --repo github.com/acme/shop --branch main --commit "$COMMIT"

The card says "No scans uploaded yet"

No scan of the team has found the flag. Run the scan with --dry-run in the checkout and look for the flag key in references. If the key is missing, check that the code uses the key in a call or a whole literal (What the scanner finds).

A repository shows "Not scanned recently"

Its default branch was not scanned in the last 7 days. Check that the CI job runs on pushes to that branch, and that its last run passed.