Troubleshooting

Maven cannot be found

Argus does not bundle Maven; it runs mvn as a subprocess to build the SBOM and to qualify patches. If mvn is not on the PATH, scanning and validation both fail immediately. Confirm the same Maven you build your project with is reachable, and that a compatible JDK is too:

reactor_unsupported

Multi-module (reactor) builds have been fully supported since 2.12.0, so this refusal only appears when reactor handling has been deliberately disabled with ARGUS_REACTOR=off (or the component input reactor: "off"), typically during a staged rollout. Remove the override to let Argus route fixes across the modules, or keep it and run module-by-module.

The SBOM build fails

The SBOM comes from a real Maven build via the cyclonedx-maven-plugin, so anything that breaks your build breaks the scan: an unresolvable dependency, a missing private repository credential, an incompatible JDK. Try building the project yourself in the same environment first; if mvn cannot resolve your project, Argus cannot either. Pass extra arguments through with --maven-args if your build needs a profile or a settings file.

Nothing is published

If scan works but run opens no merge requests, the cause is almost always the token. Publishing reads GITLAB_PRIVATE_TOKEN; if it is unset, malformed, or lacks API access to create branches and merge requests in the target project, publication silently produces nothing. Check the token is present, masked, and scoped correctly. Also confirm --project-id (or CI_PROJECT_ID) points at the right project. See GitLab CI/CD.

No vulnerabilities found

An empty report can be genuine, but if you expected findings, check two things. First, the cache: hydrated advisories live under .argus-cache/ for 24 hours, so a stale cache can mask a freshly disclosed advisory. Clear the directory or shorten --cache-ttl to force a re-fetch. Second, the config.yml libraries policy: an over-broad upgrade: never match (a com.acme.* prefix covers every group beneath it), or a forgotten ignore_advisories entry, can silence more than you intended.

Your scanner flags a CVE Argus does not see

GitLab dependency scanning uses GitLab’s own analyst-curated advisory database; Argus reads OSV.dev by default. Advisory databases differ in what they map to package coordinates and when, so a CVE can appear in one and not the other at a given moment. Confirm the difference by querying OSV for the coordinate and version the scanner names; zero results while the scanner flags it means the two databases disagree today, and Argus is working as designed on its default source.

The fix is a declared advisory with the id, package, and fixed version from the scanner’s finding. The next run plans the fix, marks the advisory (declared in config.yml), and keeps any pin that protects against it. OSV takes over automatically once it publishes the id. Keep the declaration until then, even when the run says an Argus pin is holding the coordinate clear: removing it is what lets cleanup judge the pin unnecessary.

Argus 3.7 and 3.8 could read the GitLab vulnerability report directly through the gitlab entry in advisory_sources. That source was removed in 4.0.0: once a pin fixed a finding, the report stopped listing it and cleanup removed the pin. The reverse skew, where Argus has fixed something the scanner still shows, is usually scanner-cache lag on the default branch.

Inconclusive qualification

A patch that ends qualification_inconclusive means Maven could not be run to a verdict, often because of a transient network or repository error during validation. Set ARGUS_VALIDATION_RETRIES to a positive integer so Argus retries transient failures before giving up. The merge request is still published, deliberately, so a human can review the build evidence; see Validation policies.