Troubleshoot
Each entry gives the symptom, its cause, and the fix. Status codes and messages of the upload API are listed in the upload API reference; log messages in the logs reference.
Uploads
Upload answers 401
a valid upload token is required in the Authorization header (Bearer): the request has no
Authorization: Bearer … header, or the token is unknown, revoked, or a project’s upload token
that was renewed since.
- Check that the CI secret is set and reaches the job. On GitHub, workflows triggered by pull
requests from forks get no secrets, so the header is
Bearerwith nothing after it. - Check the token in Settings → API tokens: its first characters, whether it is revoked, and when it was last used. A token that was never used never reached nanobom.
- A project’s upload token is shown on the project page under Upload token: compare it with the CI secret, and update the secret after each Renew. Other tokens are shown once: if in doubt, create a new one and revoke the old one.
- A token revoked while its upload waited for the evaluation also gets this answer; the SBOM was stored anyway (see waiting for the evaluation).
Upload answers 403
this token does not allow uploads to this project: a project token was used for another project
of the organization. Fix the project slug in the URL, or use the token of that project.
this token is read-only: uploads need a token with the upload scope: the token was created
with the Read only scope, for the read API. Create a token with
the Upload and read scope for CI.
Upload answers 404
not found, for one of these reasons:
- the organization slug in the URL is wrong, or the token belongs to another organization (nanobom does not say which, so as not to reveal which organizations exist);
- the token is a project token and the project does not exist, or no longer does: the slug in the URL differs from the token’s project, or the project was deleted with its tokens. Project tokens never create projects. Create the project on the organization page (New project) and use its upload token, or upload with an organization token.
Upload answers 413
The SBOM is larger than the limit. The limit may be:
- nanobom’s,
NANOBOM_MAXIMUM_SBOM_SIZE(16 MiB by default); the answer is then plain text, not JSON. Raise the limit, or split the SBOM; - the reverse proxy’s: nginx accepts 1 MiB by default and answers with an HTML page. Set
client_max_body_size(see Run behind a reverse proxy).
Very large SBOMs often list each file of an image; generators can usually list packages only.
Upload answers 422
The error field says what is wrong; the
upload API reference lists the messages. The usual
ones:
the SBOM must be a CycloneDX JSON document (…) or an SPDX JSON document- the generator’s default format, or another JSON file: ask for CycloneDX JSON or SPDX JSON explicitly (Syft:-o cyclonedx-json=sbom.jsonor-o spdx-json=sbom.json);XML SBOMs are not supported,SPDX tag-value documents are not supported,SPDX RDF documents are not supported- the same SBOM in another serialization: switch the generator to JSON (Syft-o spdxand Trivy--format spdxwrite tag-value; usespdx-json);unsupported CycloneDX version- the generator writes a version older than 1.3, or newer than 1.7;unsupported SPDX version- SPDX older than 2.2, or SPDX 3.0;the project slug must be …- the project name in the URL contains spaces, slashes or other characters.${GITHUB_REPOSITORY#*/}and$CI_PROJECT_NAMEare usually fine; a repository name with a dot at the start or with upper-case letters is folded or refused;fail_on=exploited needs exploitation data (NANOBOM_EXPLOITATION_DATA)- exploitation data is off on this instance: gate on a severity instead.
Upload answers 409
That is the gate doing its job: open findings reach fail_on. The response lists them in
evaluation.findings. Fix them by upgrading the components, or ignore the ones that do not
apply, with a reason (see Triage findings); ignored findings do not count.
With fail_on=license, components have forbidden licenses: the components are listed in
evaluation.licenses.violations. Replace them, or change the policy
(Enforce a license policy).
Upload answers 503
the evaluation did not complete, with fail_on: the run failed (evaluation.status is
failed) or did not finish in time (timed_out). The SBOM is stored; only the gate could not
decide.
failed: nanobom could not reach OSV. Look forrun failedin the logs, and check that the instance can reachhttps://api.osv.dev/.timed_out: the run took longer thanNANOBOM_UPLOAD_WAIT_SECONDS, often because it waited behind another run, such as the nightly run of a large instance. Retry, raise the setting, or move the schedule away from your busiest CI hours.
too many uploads are waiting for their evaluation, with wait or fail_on: a burst of CI jobs
reached NANOBOM_MAX_WAITING_UPLOADS. Nothing was stored: send the upload again after the
seconds of the Retry-After header, spread the jobs out, or raise the setting
(configuration).
Upload answers 502 or 504 after a minute
A reverse proxy between CI and nanobom gave up on a waiting upload (most default to 60 seconds).
nanobom still finishes the run. Raise the proxy’s read timeout above
NANOBOM_UPLOAD_WAIT_SECONDS, or lower the setting: see
Let uploads wait through your proxies.
Components without package URL
The response’s components_without_purl is not zero, and the project page says some components
cannot be checked. OSV matches components by package URL, so those are invisible to it. The
skipped list in the response names them with the reason (no package URL, or an invalid one).
The project’s Components tab lists the components that were stored, and counts those left
out.
Usually the generator could not identify them: vendored code, binaries copied into an image, packages installed outside a package manager. Use the generator of the ecosystem instead of a generic scanner where you can (see Generate an SBOM). Components that are genuinely your own code have no package URL, and need none.
A project appeared twice, or with an unexpected name
Organization tokens create a project for each new slug, so a typo or a renamed repository creates a new project. Delete the unwanted one from its page (admins), and switch the pipeline to the project’s upload token, shown on the project page, which cannot create projects.
Findings
No findings at all
Check, in order:
- Did a run happen? The organization page lists Recent runs. With
NANOBOM_RUN_AFTER_UPLOAD=false, a project waits for the nightly run or a Check now. - Did it succeed? A failed run leaves findings as they were, so a new project stays empty.
- Are the components checkable? The project page shows the component count and warns about components without package URL. Components whose package URL has no version cannot be matched.
- Does OSV cover them? OSV covers language ecosystems and several Linux distributions; it does not cover everything (some distributions, firmware, proprietary software).
An SBOM of up-to-date dependencies may simply have no known vulnerabilities.
Findings were fixed, but nothing was upgraded
Each upload replaces the project’s components: a component missing from the new SBOM fixes its
findings. Typical causes are an SBOM generated from a different directory, a partial build, a
per-crate SBOM of a workspace instead of the binary’s, or development dependencies left out where
they used to be included. Compare component_count across uploads in the project’s
Upload history.
A finding has an unexpected severity
Severity comes from the highest-rated record among the finding’s aliases, using the most recent CVSS version available. A GitHub advisory and the CVE it aliases can rate the same issue differently; nanobom shows the higher. See Severity.
No finding is known exploited
- Only CVEs are looked up: findings without a CVE among their identifiers have no exploitation data.
- Exploitation data is refreshed after successful runs; check
nanobom_exploitation_refresh_failures_totaland look forrefreshing exploitation data failedin the logs. The instance must reachwww.cisa.govandapi.first.org. NANOBOM_EXPLOITATION_DATA=falseturns it off.
A webhook does not arrive
- Settings → Recent deliveries lists the recent deliveries, their state and the last answer: an HTTP
status from your receiver, or a network error. Sending means the first attempt is in
progress; Retrying means the receiver failed and another attempt is scheduled; Failed
means it refused the document (a
4xx), every retry failed, or the webhook was removed, disabled or moved to another URL after a failed attempt; Cancelled means the webhook was removed, disabled or moved before any attempt was recorded. - The webhook must be Enabled, and findings must reach the minimum severity (or be known exploited). With Only known exploited vulnerabilities, nothing else is sent.
findings.newis only sent for new, reopened or newly exploited findings: a finding that was already open is not sent again.projects.staleis only sent after scheduled runs.- Deliveries must be answered within 15 seconds. Failed ones are retried after 1 minute, 10 minutes and 1 hour, then abandoned.
An email does not arrive
- If Settings → Email notifications says email is off, the operator has not set
NANOBOM_SMTP_URL(andNANOBOM_SMTP_FROM); see Send them by email. - Send a test email shows the SMTP server’s reply for each address it refuses:
535means the credentials inNANOBOM_SMTP_URLare wrong,550or554that a recipient or the sender is refused. A network or TLS error means nanobom cannot reach the server with the scheme and port given (smtps://uses port 465,smtp://…?tls=requiredport 587). - Recent deliveries lists one line per recipient, marked Email to and the address, with
the SMTP server’s last reply. A
5xxreply is not retried. - nanobom does not start: a
smtp://URL with a user or password needs?tls=required(or usesmtps://), so that the credentials are not sent in clear text. - An email accepted by the server (Delivered) but not in the inbox is in the hands of the mail system: look in the spam folder, and check that the sender’s domain allows the SMTP server to send for it (SPF, DKIM).
- The same filters as for webhooks apply, with the email’s own minimum severity and Only known exploited vulnerabilities.
A run failed with “the run stopped unexpectedly”
The run did not end normally: a bug made it panic (look for a stage of a run panicked in the
logs, and report it), or nanobom was stopped or crashed while it was running, in which case it
was closed at the next start. It is not resumed; the next run of the same scope does the work.
Interface
Forms answer “cross-site request refused”
The browser’s address does not match NANOBOM_PUBLIC_URL: another host name, http instead of
https, or another port. Set NANOBOM_PUBLIC_URL to the address you use, or use the address it
names.
Signing in returns to the sign-in page
The session cookie is not kept. Most often NANOBOM_PUBLIC_URL is https://… while you browse
over plain http: the cookie is then marked Secure, and the browser does not send it back.
Pages have no styles
nanobom cannot find its assets: NANOBOM_SITE_ROOT must point at the site directory of the
release. In the image, it is set to /app/site.
Sign-in answers 429
Too many failed attempts from the same address: wait a few seconds. If every user is limited at
once, nanobom sees all requests coming from the reverse proxy: set
NANOBOM_TRUST_FORWARDED_HEADERS=true, only behind a proxy that replaces X-Forwarded-For (see
Run behind a reverse proxy).
Single sign-on
The sign-in page shows a short message, and the logs say why:
| Message | Cause |
|---|---|
| The identity provider could not sign you in | Discovery failed, the provider refused the sign-in (wrong redirect URI or client secret), or its answer could not be verified; see the OpenID Connect sign-in refused or starting the OpenID Connect sign-in failed log line, and below |
| The sign-in took too long; please try again | The session cookie set when leaving for the provider was not sent back: the sign-in took longer than the session, or the public URL’s host or scheme differs from the address in the browser |
| This account is not known here and new accounts are not created automatically | NANOBOM_OIDC_CREATE_USERS=false and the user never signed in |
| This account is disabled | An instance administrator disabled the user |
The provider reports a redirect URI mismatch
The redirect URI nanobom sends is NANOBOM_PUBLIC_URL followed by auth/oidc/callback. Register
exactly that at the provider, scheme, host and port included: if NANOBOM_PUBLIC_URL was left at
its default, nanobom sends http://localhost:8080/auth/oidc/callback.
“The identity provider could not sign you in”
The logs say why (OpenID Connect sign-in refused or starting the OpenID Connect sign-in failed):
the identity provider could not be reached- nanobom cannot fetch<issuer>/.well-known/openid-configuration: wrong issuer, provider unreachable from nanobom’s network, or a redirect (anhttpissuer redirected tohttps, for example), which nanobom does not follow;unexpected issuer URI- the issuer in the discovery document differs fromNANOBOM_OIDC_ISSUER. Copy it exactly from the discovery document, including a trailing/if there is one;the identity provider refused the sign-in- usually a wrong client secret, or a client not allowed to use the authorization code flow.
Groups or administrator rights are not applied
- Roles from groups and the administrator claim are applied at sign-in: sign out and in again after changing them at the provider.
- The claim must be in the ID token or in the user information. Many providers put groups and roles in the access token only by default, which nanobom does not read; see the provider examples.
NANOBOM_OIDC_GROUPS_CLAIMmust name the claim exactly, as a top-level name or a dotted path (realm_access.roles).- Group names in
NANOBOM_OIDC_GROUP_MAPPINGmust match the claim’s values exactly; Keycloak sends/developerswith Full group path on.
An administrator lost their rights after signing in
With NANOBOM_OIDC_ADMINISTRATOR_CLAIM set, the claim decides at each sign-in, and removes rights
given in the interface from users who do not have it. Grant the claim at the provider instead.
Startup errors
| Message | Fix |
|---|---|
no sign-in method | Enable local accounts or configure OpenID Connect |
OpenID Connect needs both NANOBOM_OIDC_ISSUER and NANOBOM_OIDC_CLIENT_ID | Set both, or neither |
invalid NANOBOM_SCHEDULE | Use a five-field cron expression, or off |
invalid NANOBOM_OIDC_GROUP_MAPPING | Fix the entry named in the message: group=organization:role |
invalid value '' for '--failure-webhook-url …' (or another option) | An empty variable: remove it instead |
unable to open database file | The database’s directory does not exist or is not writable by nanobom’s user (65532 in the image) |