Troubleshooting
Start with the agent's service.log, next to its configuration file (see Agent command line for the paths), and the device's row in Fleet Health.
Agents
| Symptom |
Check |
| The device never appears in Agents |
The installer's enrolment token may have expired (30 days) or been revoked. Download a fresh installer. Check the device can reach your server's address over HTTPS. |
| Setup failed on Windows |
Read Backup-Agent-Install.log in the Windows temp folder. Setup must run as administrator. |
| The service runs but nothing is backed up |
No backup passphrase is set yet. Set it in the desktop app on Windows, or with cvn-agent install and CVN_PASSPHRASE elsewhere. |
| "Back up now" does nothing |
The command needs the agent's live connection. Check the device is online in Agents. |
| Backups fail with no storage error |
The tenant has no storage target. Assign one under Storage > Assignments, or set an active vault. |
| A backup aborted with "breach detected" |
A canary file was altered. Investigate the device before you run another backup. See Immutability and ransomware. |
| A database source fails |
The dump tool (mysqldump, pg_dump or sqlcmd) must be installed on the device and on its PATH. The job error shows the tool's message. |
| A device was renamed or re-enrolled |
Devices are keyed by hostname within a tenant. A machine that re-enrols with the same hostname takes over the old record. |
cvn-agent backup exits at once on Windows |
Antivirus may have quarantined the agent. Allow it in your antivirus policy. |
| An agent stays on an old version |
Signed self-updates arrive with version 1.0. Agents check every six hours and only install builds whose release signature checks out. Use Update in Remote Engine, or run cvn-agent update --check on the device. |
Restores
| Symptom |
Check |
| "Couldn't unlock" in File Explorer |
The passphrase is wrong, or the restore point is on SMB or NFS storage, which the server cannot read. Restore in place or on the device instead. |
| Restores in the browser fail with "unavailable" |
Maintenance mode is on, or the tenant's S3 target is unreachable. Check its health under Storage. |
| An old restore point will not decrypt after a passphrase change |
Old restore points need the passphrase they were made with. Set CVN_PASSPHRASE to the old one for that restore. |
| Restore in place does nothing |
The device must be online. Progress shows under Restores. |
Storage
| Symptom |
Check |
| A target shows as unhealthy |
Use Test connection on the target. Check the endpoint, bucket, keys and, for MinIO, path-style addressing. |
| Object Lock errors on the first backup |
The bucket was created without Object Lock. Create a new bucket with Object Lock turned on. |
| Pruning leaves objects behind |
Objects under Object Lock cannot be deleted before their date. A later prune removes them. |
| Usage looks high after a key rotation or a passphrase change |
The first backup after either one uploads the device's data again, because chunk names change with the key. Prune old restore points when retention allows. |
| A tenant cannot add backups |
It reached its storage cap. Raise the cap or prune. |
| Replication is not copying |
Replication runs only between S3 targets, and only with Replicate to a secondary target turned on in Settings > Storage & retention. |
Sign-in
| Symptom |
Check |
| No invitation or reset email arrives |
SMTP is not set up. The link is in the server log instead. |
| A tenant's users are refused at sign-in |
Check the tenant's IP allow-list, and that the tenant is not suspended or terminated. |
| The IP allow-list or audit log sees the proxy's address |
Behind a reverse proxy, set CVN_TRUSTED_PROXIES in the server configuration to the proxy's addresses so the real client IP is used. |
| SSO sign-in fails |
The identity provider must send a verified email that matches an existing, active account. |
| Too many attempts |
Sign-in is rate limited per IP. Wait a minute and try again. |
Still stuck
Open a support ticket from your account at account.cvntechnologies.com, or search and report issues on the public issue tracker linked at the bottom of each docs page. Include the agent's service.log and the time of the failure. Remove passphrases and keys before you send any file.
Edit or report a problem