Troubleshooting
Start with the symptom below. For a failed run, open its log and note the stage and error message; then use the checks for that source or feature.
Agent shows offline
An agent appears offline when it has not checked in recently, and its backups pause until it reconnects. Confirm the server is running, outbound HTTPS access to vectaapp.com works, /etc/cron.d/vecta contains the scheduled entry, and /var/log/vecta-agent.log is changing. The cron entry should invoke the agent every couple of minutes. If the file is missing or the log stops changing, repair the installation or run the agent's manual command described in Agents.
Agent says root privileges are required
On Linux, run operational commands with sudo: sudo vecta-agent register --token <TOKEN>,
sudo vecta-agent setup <JOB_ID>, sudo vecta-agent repo init <DESTINATION>,
sudo vecta-agent run, or sudo vecta-agent update. version and help work without root.
If the command must run as the current user, put --allow-non-root before the subcommand, for
example vecta-agent --allow-non-root run; protected paths may not be accessible.
vecta-agent hooks list and vecta-agent hooks validate are read-only and can run without sudo.
Job is running or has a stalled badge
Check whether the machine slept or the agent stopped, then inspect /var/log/vecta-agent.log. If the process is no longer making progress, use Stop. If the agent is unreachable or Stop is not enough, use Mark as failed, then Run now after the agent returns.
Backup fails with an authentication-style error
Read the failure dialog or email for the agent's message tail. The usual cause is missing or stale destination credentials. Re-run setup on the agent:
sudo vecta-agent setup <JOB_ID>
Replace <JOB_ID> with the job ID. Run setup again after changing a destination because credentials are keyed to the destination string.
SFTP backup fails
SFTP uses SSH keys only; password authentication is not supported. Check the user, host, path, and port in the job. Confirm that the agent user's public key is authorized on the destination host. Setup probes the connection and prints ssh-keygen and ssh-copy-id commands when it finds a key problem.
PostgreSQL capability is unavailable
Open Agents → Capabilities to see the missing requirement. PostgreSQL jobs need pg_dump
9.0 or newer and Restic 0.17.0 or newer with stdin-command and stdin-filename support. Install or
upgrade the tools, then run sudo vecta-agent hooks publish to refresh the report immediately,
or wait for the next agent run. This command sends a report; it does not start a backup.
If setup reports a PostgreSQL connection error, verify the host, port, database, username, SSL mode, and network access from the agent machine. Confirm the database account can read the schema and data. Setup performs a schema-only connection test; it does not test a full dump or upload.
Hook is missing or cannot run
The hook must be present in the agent's valid local catalog and allowed for the selected pre/post
phase. Check it with vecta-agent hooks list and vecta-agent hooks validate, then publish
changes with sudo vecta-agent hooks publish. The catalog, its parent directories, and
executable must be root-controlled. Non-root hooks also require their configured service account
to exist. Unknown, changed, or unsafe hooks fail closed. See Database Backups and Hooks.
PostgreSQL run failed after a snapshot was created
Check the run's stage details. If PostgreSQL dump and Restic both completed but the post-hook failed, the overall run is marked failed even though the snapshot is usable. The Logs restore action remains available for that completed archive; see Restoring Data.
Job succeeded with a warning
warning means a snapshot was created but zero files were processed. Check the source path on the agent machine for a typo, an empty directory, or a path that the agent cannot read. This is not a failed run, but it may not contain the data you intended to back up.
Run now did not start anything
Run now flags the job; it does not start a process in the dashboard. The agent sees the flag at its next check-in, usually within about two minutes. If the agent is offline, fix that first.
Registration token expired or was already used
Create a new registration token. Tokens are valid for 24 hours and can be used once.
Verification or password-reset email is missing
Check spam and search for mail from Vecta. Resend from the verification gate or login screen. If the message still does not arrive, contact support@vectaapp.com.
Schedule runs at the wrong time
Schedules use UTC and do not have a timezone setting. Convert the intended local time to UTC, edit the job, and wait for the next check-in after the schedule takes effect.
Repository password or API key is lost
The repository password is unrecoverable; data in that repository cannot be read without it. See Your repository password. The agent API key is also shown once; delete the agent and register it again. See Your agent API key.
Backups are slower or larger than expected
The first run transfers the source data. Later runs are deduplicated, so transferred can be much lower than processed. A very large first run may reach the maximum duration of roughly half a day. Split the source into multiple jobs if one run cannot finish within that window.
What's next
Check Current Limitations for known beta behavior, or use Reference for paths and commands.