Troubleshooting

Each entry below gives the message you see, the cause and the fix. Messages are quoted as the binary prints them; vulkro-sf prints the same text with its own name. Three commands answer most questions:

vulkro --version
vulkro license-status     # licence state, plan and this machine's ID
vulkro env network        # every network switch and what it does

Exit codes

Code	Meaning
0	Success, and no findings at or above --fail-on.
1	Findings at or above --fail-on, a gate block, or a licence block.
2	An error: bad arguments, a missing path, an IO failure, a refused network call, or a crash.

A licence block and findings are both 1. A licence block always prints the line vulkro: license_required on stderr (vulkro-sf also prints vulkro-sf: license_required), so CI can tell them apart with grep -q '^vulkro: license_required'. With --format json, ndjson or sarif, a failed run also prints an error document on stdout whose error.reason names the cause: license_required, bad_arguments, path_not_found, permission_denied, config_invalid, io_error, network_error, internal_error or error. See Exit codes.

Licences

You see	Cause	Fix
No active Vulkro Pro licence on this machine, so `vulkro` will not scan. (exit 1)	This machine has never signed in, or it signed out.	Start the 14-day trial at app.vulkro.com/billing, then run vulkro login.
Vulkro license expired on DATE: grace period ends in N days, then scanning stops.	The signed lease passed its expiry. Scanning keeps working for 14 days of grace, offline too.	If your plan is active, run any command with network access: the lease refreshes on its own (not with --offline, VULKRO_OFFLINE or VULKRO_NO_HEARTBEAT). Otherwise renew at app.vulkro.com/billing.
The licence lapsed on DATE and its 14-day grace has ended.	The grace period is over. Your scans and reports stay on disk and readable.	Renew, then run vulkro login (or install a new .lic).
VULKRO_OFFLINE is set, so vulkro cannot ... (this contacts the account server).	Signing in needs the network.	Air-gapped: create an offline licence file at app.vulkro.com/connect for the ID from vulkro machine-id, then run vulkro activate with that .lic file.
this license is bound to a different machine.	A .lic file is made for one machine ID.	Create a file for this machine, or email support@vulkro.com to transfer it.
this key is for a different product	A vulkro-sf file given to vulkro activate, or the reverse.	Run activate with the binary the message names.
signature did not verify - key may be forged, corrupted, or signed by the wrong issuer	The .lic file was edited or damaged in transit.	Download the file again. If it still fails, email support@vulkro.com.
detected the system clock was set backward.	The clock is more than 24 hours behind the last recorded run.	Set the correct time (turn on network time) and run again.
license database appears modified - trial integrity check failed.	The local licence database was changed by hand.	Email support@vulkro.com.

In CI, nobody can run vulkro login. Set VULKRO_ACCOUNT_TOKEN to a CI key (portal: Settings, Credentials) and the scan signs in by itself on its first run. On an air-gapped runner, set VULKRO_LICENSE_B64 to the base64 of a .lic file instead; it is checked in memory and never written to disk. When either variable is set but does not work, the refusal adds a line saying why.

The scan examined no source file

! no source file under PATH was examined: this build has no extractor for ...
✗ Exiting 2 - no source file was examined, so this scan is not a clean result.

Cause: nothing in the folder is in a language vulkro reads (JavaScript / TypeScript, Python, Go, Java, PHP, C, C++), for example a Ruby, C# or Kotlin project, or a folder of templates or docs. "No findings" would mean "nothing was looked at", so the scan never exits 0. It exits 2 when nothing was reported, and 1 when the checks that need no language support (dependency lockfiles, containers, IaC, secrets) still found something. --format json sets stats.unexamined_tree.

Fix: point the scan at the folder that holds the code. Apex and other Salesforce code is scanned by vulkro-sf scan; when the folder holds Apex, the message says so.

vulkro-sf refuses the path

vulkro-sf: PATH holds no Salesforce source or metadata (no sfdx-project.json, Apex, LWC, Aura, Flow, Visualforce or -meta.xml file) ...

Cause: vulkro-sf scan was pointed at a folder with no Salesforce files. It exits 2 rather than report a non-Salesforce tree with general rules.

Fix: point it at your SFDX project or retrieved metadata folder, use vulkro scan for other code, or pass --force to scan the path anyway.

Stale or missing CVE data

Once CVE data is installed, every table-mode scan ends with a line like Vulnerability data last updated 2026-10-12 (7 days ago). Run vulkro update to refresh.

You see	Fix
An old date in that line	Run vulkro update. It refreshes the signed CVE bundle (and offers a newer binary when one exists).
CVE bundle is N hours old ..., older than the --max-bundle-age H hour limit.	The same. --max-bundle-age only warns; add --max-bundle-age-fail to make a stale or missing bundle exit 2 in CI.
no local CVE bundle was found under ~/.vulkro/data/cves	Run vulkro update once. Until then, dependencies are not checked for CVEs.
VULKRO_OFFLINE=1 is set - refusing to make network calls. Apply a local bundle instead	On an air-gapped machine, copy a .vkbundle file across and run vulkro update --bundle with its path.

Network: proxies and offline mode

A corporate proxy breaks login, update or the installer. A TLS-inspecting proxy presents its own certificate. Vulkro trusts the built-in Mozilla roots plus the operating system's certificate store, so the usual fix is to install the proxy's CA in the OS store. Otherwise set SSL_CERT_FILE to a PEM bundle that includes it, or SSL_CERT_DIR to a folder of certificates (either one replaces the OS store; the built-in roots stay trusted). An authenticating proxy is set with HTTPS_PROXY=http://user:pass@proxy:port.

A command refuses because offline mode is on. --offline (on vulkro) or VULKRO_OFFLINE blocks every outbound call. Commands whose job is the network then stop with exit 2 and a message such as VULKRO_OFFLINE=1 is set; refusing to .... Scans keep working offline. To go online, drop --offline and unset VULKRO_OFFLINE. Any value except 0, false, no and off (an empty value included) turns offline mode on; setting one of those four prints a warning that offline mode is off.

A slow scan

• See where the time goes. vulkro scan . --timings --format json records the time of each pass, slowest first, in stats.pass_timings. It changes no finding.
• Scan less. Point the scan at one service (vulkro scan ./services/api), or scan only the files changed against a branch with --diff-only origin/main.
• Cap the time. VULKRO_SCAN_BUDGET_SECS=300 stops starting new passes after 300 seconds. The skipped passes are named in degraded_passes and a partial-results warning is added, so a capped scan never looks complete.

Permission errors on ~/.vulkro

You see	Fix
could not create ~/.vulkro. Try: check the permissions on your home directory.	Usually a past sudo vulkro ... left the folder owned by root. Take it back with sudo chown -R "$(id -un)" ~/.vulkro, and do not run Vulkro with sudo.
could not determine your home directory to locate ~/.vulkro/scans.db.	Set HOME (USERPROFILE on Windows), or set VULKRO_DB to a writable file path.
error.reason = "permission_denied" on a scan	A path you asked for, or the output file, cannot be read or written. Check the path the message names.

VULKRO_DB moves the whole local database, including the signed-in session, so a machine pointed at a new path has to sign in again (or use the CI key).

Colour, hints and noise in CI logs

• -q / --quiet keeps stderr to warnings and errors. Results on stdout and exit codes do not change.
• --no-color, a non-empty NO_COLOR, or TERM=dumb turns colour off.
• Tips and next-step hints print only on an interactive terminal, and never when CI is set or --quiet is on.

Both flags work the same way on vulkro-sf.

Getting help

Email support@vulkro.com with the output of vulkro --version, the command you ran, the full error text, and your operating system. For a licence problem, include the output of vulkro license-status (it shows your machine ID). Do not send source code: we do not need it to diagnose an error.