Skip to content

Troubleshooting

Start with the distributed prerequisite checker and the CLI/IDE output. Preserve the first stable error identifier and exit code; later messages can be consequences of the first failure.

Symptom index

Symptom Start here
Java, OpenGrep, IDE, or container not ready Run diagnostics
License error [...] or exit 3 License failures
OpenGrep command not found OpenGrep is not found
Scan appears stuck or quiet Scan appears quiet
Empty or unexpectedly small report Reports are empty
Docker/Podman mount or permission failure Container volumes fail
IDE report panel is blank IDE report does not open
Viewer does not recognize files Viewer cannot load reports

Run diagnostics first

.\postq-code-scanner-preinstall-check.ps1

bash ./postq-code-scanner-preinstall-check.sh

For container-only usage, select the container profile. For CLI and IDE usage, select runtime. Run diagnostics as the same account that runs the scanner.

License failures

Run status without scanning:

postq-code-scanner-cli --license-file /secure/postq.lic --license-status

Check, in order:

  1. The file exists and the scan account can read it.
  2. The file was not edited, reformatted, truncated, or pasted through a lossy system.
  3. Host UTC time and time synchronization are correct.
  4. The signed license and beta windows are active.
  5. Repository and eligible-file limits are not exceeded.
  6. The local ledger exists, is writable, and has not been modified or rolled back.

Do not attach postq.lic or the ledger to an unprotected support request.

OpenGrep is not found

Verify:

opengrep --version

Set an explicit command:

export POSTQ_OPENGREP_PATH=/usr/local/bin/opengrep

$env:POSTQ_OPENGREP_PATH = 'C:\Tools\OpenGrep\opengrep.exe'

Or pass --opengrep-path on the scan command. In an IDE, configure the equivalent PostQ OpenGrep setting because a graphical host can have a different PATH from an interactive terminal.

Scan appears quiet

Large repositories can spend time in OpenGrep. VS Code and Eclipse show scanner-service output and heartbeat messages. Check CPU/memory pressure, source size, filesystem performance, and whether the OpenGrep process is still active before terminating it.

If the runner has insufficient memory, scan a representative service or language subtree. A trial license can also reject a repository that exceeds its eligible-file limit.

Reports are empty or incomplete

Check:

  • project/source path and read permissions;
  • language hint and supported coverage;
  • whether a fresh scan ran or old OpenGrep evidence was reused;
  • manifest.json inputs, warnings, and artifact list;
  • opengrep-results/opengrep-results.json for raw matches;
  • unresolved parameters and unverified library evidence;
  • whether the selected source actually contains APIs represented by maintained rules.

An empty report is not proof that the source is crypto-free.

Container volumes fail

  • Use absolute host paths on CI runners.
  • Create the report directory before the run and confirm it is writable.
  • Mount source :ro, reports :rw, and the license :ro.
  • Confirm the image architecture matches the runtime VM.
  • On Windows/macOS, allow the runtime VM to access the selected drive/folder.
  • On SELinux, use the organization-approved labeling option when required.

Do not remove --read-only to solve a report mount error; fix the specific writable report or temporary mount.

IDE report does not open

  1. Confirm the scan completed and its report folder still exists.
  2. Open the PostQ output/console and locate the first error.
  3. In VS Code, use Show Output and confirm the configured scanner/OpenGrep paths.
  4. In Eclipse, review Error Log, PostQ console, SWT Browser support, and WebView2 on Windows.
  5. Load the same folder in the standalone Report Viewer to separate report-data problems from host rendering problems.

Viewer cannot load reports

  • Extract the complete viewer archive before opening index.html.
  • Use Load Folder for a complete scan directory.
  • Confirm the JSON is valid and includes schemaVersion, generatedAt, and scanSession.
  • Do not rename files if a consumer identifies reports by their standard names.
  • Avoid combining files from different scan sessions or incompatible schema versions.

Information to collect

Collect product version, operating system/architecture, Java and OpenGrep versions, redacted command options, exit code, first error identifier, scanner logs, and manifest.json. Share source and raw reports only through an approved secure support process.