How-to guides/Troubleshooting

Troubleshooting

Edit on GitHub ↗

Common failures, PATH issues, plugin discovery, missing output, policy errors.

pvtr: command not found

Check whether the binary exists where you installed it:

Get-Command pvtr
ls $HOME/.privateer/bin/pvtr
ls /usr/local/bin/pvtr

If found, the install directory is not on PATH:

export PATH="$PATH:/usr/local/bin"
source ~/.bashrc

permission denied

chmod +x /usr/local/bin/pvtr

On macOS, approve the binary through Gatekeeper: System Settings → Privacy and Security.

Plugin not discovered

pvtr list --installed    # check what Core can see

The plugin value in config must be the installed coordinate exactly as pvtr list shows it, such as openssf/github-repo (see target settings). A plugin binary copied into the binaries path by hand is not discovered; install it with pvtr install --local <path>. If using a custom binaries path, pass it consistently:

pvtr run --binaries-path /opt/pvtr-plugins

Or set it in config:

binaries-path: /opt/pvtr-plugins

No output files

Verify in config:

write: true
write-directory: evaluation_results   # must be a writable path

Then increase verbosity to identify the failure:

pvtr run -c config.yml --loglevel debug

Policy validation error at startup

A missing policy, an unknown catalog, or an applicability value that matches nothing each fail differently; the policy reference lists the symptom and exit code for each. Check the plugin’s documentation for valid catalog IDs and applicability values.

Plugin crash

A plugin that panics or exits unexpectedly ends with an internal error (exit code 3); other targets are unaffected. Core does not retry. Check <target>.log for the subprocess output. Run the plugin in debug mode to reproduce the failure outside the gRPC boundary:

./my-plugin debug --target my-target -c config.yml

version returns “edge”

Built from source without a release tag. Expected behavior for development builds. Use a release binary in production pipelines.