Troubleshooting
Start with the logs of the server and the status of the agents. Most problems show up in one of them with a clear message.
The server does not start
- It exits with a Redis error. Redis must be reachable when the server starts. Check
REDIS_ADDR, the password and the network. Test it withredis-cli -h <host> ping. - It exits with an S3 error. The S3 endpoint, the keys and the bucket are required at start. The
bucket is created when it is missing, so the keys need that right. Check
S3_ENDPOINTwithout a scheme, andS3_USE_SSLandS3_PATH_STYLEfor your store. MinIO needs path style. - Migrations fail. Read the first error in the log. With PostgreSQL, MySQL or MSSQL, a failed migration job stops the Helm upgrade; the server pods wait for it. Fix the database and run the job again.
- The page loads, but the sign-in fails. Check
INITIAL_ADMIN_PASSWORD. The initial administrator is only created when the database is empty; changing the variable later does not change the password.
An agent does not report
Look at the agent first, then at the server.
- On a host, check the service:
systemctl status vop-agent(Linux),sc query vop-agent(Windows), orsudo launchctl list | grep dev.vop.agent(macOS). Its log tells you whether the server is reachable and whether the key is accepted. - The key is rejected: the agent was disabled, its key was rotated, or it was deleted. Rotate the key and copy the new one into the configuration file, or reinstall with a new install command.
- The server cannot be reached: check
serverUrl, the certificate, and the proxy in front of the server.insecureSkipVerifymust not be the cure for a certificate that is not trusted; install the CA instead. - A Kubernetes node agent cannot register: the cluster token was deleted or renamed, or the node name is not a valid Kubernetes node name. A name that belongs to an agent of another cluster or another type is refused too.
- The agent is online but its assets are missing: the server rejects an inventory whose kind does not fit the agent type. A host agent sends hosts; a Kubernetes agent sends containers and its node. The error is in the agent log.
A scan does not finish, or assets stay pending
- Check Running now and Scan history on the Scans and tasks page.
- Until the Grype database is loaded, the worker takes no jobs and runs no scheduled tasks. The server retries the
load, backing off to five minutes. The
grype-db-loadtask says whether it succeeded. On an air-gapped installation, check thatGRYPE_DB_DIRholds a database. - A job whose worker stopped is marked interrupted and taken over by another worker, if one runs. With a single process, restart the server, and start the scan again.
- Pending assets that never clear point to an error in their scan. The server log names the asset.
Findings look wrong
- Some vulnerability data ties a CVE to a product that the CVE's NVD record does not name. The server drops those matches: the CVE's NVD record is checked once and cached. A CVE that NVD has not analysed keeps its matches until it is. A rescan after the NVD record changes applies the new answer. Each scan spends at most two minutes on these checks. NVD allows few requests a minute without an API key, so a first scan can run out of time. The matches it did not check are kept, and the next scan continues from the answers already cached. An NVD API key on the Settings page makes the first scan complete much sooner.
- A package that matched the wrong vulnerability is often a Windows program without the right CPE mapping. Check its mapping on the CPE mappings page.
- A vulnerability that no longer applies is removed after the next scan that includes the asset. Start a full rescan to refresh every asset.
Reports, exports and alerts
- A report fails: the error is in its row on the Reports page. A filter that matches too many rows, or an AI backend that does not answer within the timeout, are the usual causes.
- An alert did not arrive: open the delivery log on the Alerts page. Test the channel, and check the rule's filters.
- An export is short: the row limit,
REPORT_MAX_ROWS, applies to exports as well as to reports.
Single sign-on
See the list of common causes in Single sign-on. The most frequent one is a redirect address that differs from the one registered at the provider.
Collecting information for a bug report
Include the version of the server and of the agent (vop-agent -version prints the agent's), the log around the
time of the problem, with LOG_LEVEL=DEBUG if you can reproduce it, and the relevant configuration with the
secrets removed.