Troubleshooting

Start here when something does not work. The first section holds the three looks that answer most questions about a monitored server. The second section lists what you see, in the words you would use yourself, and each entry links to the cause and the fix.

Try this first

The examples use the port 5432. Replace 5432 with the port of your PostgreSQL instance.

See the state of the agent’s service

On the server that runs PostgreSQL, with administrator rights, show the state of the service.

Linux

sudo systemctl status guardioz-agent-5432 --no-pager

The line that starts with Active: carries the state. active (running) means that the service runs.

FreeBSD

service guardioz_agent_5432 status

The command reports whether the service runs.

A service that runs means that the agent process is up. It does not prove that the last snapshot reached Guardioz, which is what the time of the last snapshot shows.

Read the agent’s log

On the server that runs PostgreSQL, with administrator rights, show the last 50 lines that the agent wrote.

Linux

sudo journalctl -u guardioz-agent-5432 -n 50 --no-pager

FreeBSD

tail -n 50 /var/log/guardioz_agent_5432.log

Two lines answer most questions. Snapshot sent (HTTP 202) reports that a snapshot reached Guardioz. Waiting 3600s before first collection (registration already sent a snapshot). is the normal state right after a start: the agent waits one full interval, one hour as the installer sets it, before it collects. Most lines with the level ERROR have an entry in Agent and data problems.

Read the time of the last snapshot in Guardioz

In your browser, sign in to Guardioz at https://app.guardioz.com/ and open Servers. The Last seen column holds the age of the newest snapshot for each server, and Never means that no snapshot has arrived for it yet. The agent sends one snapshot per hour. The dot turns yellow when no snapshot has arrived for 90 minutes and red after 150 minutes, and Last seen gives the exact age.

For the whole procedure, with what each answer means, see Check that the agent works.

Find your problem

The installer stopped

• The installation ended with errors - the heading summarises the run; one instance carries the cause.
• It needs administrator rights - the account is not root, or sudo did not grant the rights.
• It cannot connect to PostgreSQL - PostgreSQL does not run here, or its socket is in another directory.
• No account it can use may create a role - none of the roles it tried is a superuser or has CREATEROLE.
• It cannot run commands as the account that owns the cluster - the switch to that account was refused, or psql is not reachable for it.
• Guardioz supports PostgreSQL 18 only - no instance on this server runs PostgreSQL 18.
• It did not choose a PostgreSQL instance - the server runs more than one PostgreSQL 18 instance, and the run could not ask which one to register.
• psql was not found - psql is outside the directories the installer searches.
• curl, tar, openssl or systemctl was not found - a program that the installer needs is missing.
• The Python on the server is older than 3.11 - the installer needs Python 3.11 or newer with its venv module.
• The instance is a replica - Guardioz supports the primary server only.
• pip stops with an error - the server cannot reach the Python package index.
• Python cannot create virtual environments - the venv module lives in a package of its own.
• The system account for the agent’s service exists without its group - an account with that name was created on this server before, without a group of the same name.
• Could not download agent source - the server has no outbound HTTPS connection to Guardioz.
• FreeBSD: the agent’s Python packages - the pkg repository has no Python version that ships all three.
• The command does not run at all - it is the command for another operating system, or it did not come from the setup page.

The setup page keeps waiting

• Waiting for server registration… - Guardioz received no registration for this command.
• Server registered, installing agent… - the installer’s last message did not arrive.
• The agent’s service did not start - the server is registered, and the service that collects from now on did not come up.
• Failed to generate command - the page asked Guardioz for a command and got no answer, usually because the session ended.

The install command was refused

• A message about the setup token - the command is expired, already used, or not complete.
• The plan has no place for another server - the organization already has as many servers as its plan includes.
• The account is disabled - Guardioz registers no server for a disabled account.
• Too many requests - several installations from one network address at the same time.
• The agent stopped collecting after a refused command - the run changed the monitoring role’s password before Guardioz refused it.
• The monitoring role cannot log in over the local socket - another rule in the pg_hba.conf file matches the role first.

I see no findings

• Guardioz has no data after the installation - All clear with No snapshots received yet. means that nothing has been checked.
• The initial snapshot did not reach the cockpit - that message calls Guardioz the cockpit: the server is registered, and the snapshot from the installation did not arrive.
• No new snapshot after a restart, a reboot or an update - the agent waits one full interval after every start.
• A value on a finding page reads Not measured - the measurement is not in yet, or it could not be taken.
• One dataset or one database is missing - the monitoring role cannot read that dataset or cannot connect to that database.

The server shows red

• The status dot is yellow or red - the hourly snapshot is late, or two in a row did not arrive.
• The server is still in Guardioz after you removed the agent - removing the agent changes nothing in Guardioz.

The agent log reports an error

• Authentication failed (HTTP 401) - Guardioz does not accept this agent’s collector key.
• Cockpit refused the snapshot (HTTP 422) - a wrong clock on the server, or an agent older than Guardioz expects.
• Connection error - the agent could not reach Guardioz.
• Cockpit refused the snapshot (HTTP 429) - a snapshot came less than 10 minutes after the previous one.
• Server returned HTTP 503 - Guardioz did not take the snapshot at that moment.
• Error during collection cycle - the agent could not read PostgreSQL as the monitoring role.
• The service stops right after it starts - the configuration file is missing a value the agent needs, or sets an interval below 900 seconds.
• A schedule file that cannot be read - the daily and weekly collections are suspended until the file can be used.

I cannot sign in

• Incorrect email or password - one message covers five causes, including a pause after 5 incorrect passwords in a row.
• The sign-in asks you to confirm your address - the password was right, and the address is not confirmed yet.
• This account is disabled - no sign-in method works while the account is off.
• Sign-in with Google or GitHub does not complete - three messages, each with its own cause.
• Guardioz signs you out while you work - a session ends after a period without activity, and at its maximum lifetime.
• Every page opens One last step - the account has no organization yet.

No email arrives

• No confirmation email arrives - the message is in the spam folder, the address has a typo, or it already has an account.
• The confirmation link opened a page, and the address is still not confirmed - the confirmation takes a click on the page that the link opens.
• Invalid or expired confirmation link. - the link is older than 48 hours, or it is not complete.
• No password reset email arrives - the answer is the same in every case, and three of them send nothing.
• Invalid or expired reset link. - a reset link is valid for 30 minutes.

A page answers with one line of text

• Too many requests from this network address. - one network address submitted too many forms in a short time.
• CSRF validation failed - the page was open while the session changed.
• A form was not saved - the action needed a recent sign-in first.

The update did not finish

• No snapshot arrives in the hour after an update - the agent waits one full interval after the restart.
• The URL given does not match the agent’s api_url - the address you passed differs from the one in the configuration file.
• A service did not start again - the updater reports that instance and goes on to the next.
• Usage: update-agent.sh - the script needs the Guardioz address, and stops at an argument it cannot read.
• Error: no kept version - that timestamp is not on the server, because a rollback consumes the version it restores.
• The downloaded agent does not import - the download arrived incomplete, and nothing was replaced.
• The download stops with a message from curl, fetch or tar - the server could not reach Guardioz.
• The updater needs administrator rights - the account is not root, or sudo did not grant the rights.
• No Python interpreter to verify the agent with - the Python that the agent’s service names is not installed, and the server has no python3.
• The transaction-log disk reads as not measured - an update neither grants nor repairs that permission.

Something is left after a removal

• Something is still on the server after the removal - each step undoes one change, and the install manifest is the record of them.
• The agent keeps running after you deleted the server - the deletion removes the collector key and nothing on the host.

If nothing here matches

Write to contact@guardioz.com. Get help lists what to put in the message, so that we do not have to ask for more details, and what to keep on your own server.

Next steps

Check that the agent worksConfirm the service, the log line that proves a sent snapshot, and what Guardioz shows.

Manage the agent serviceRead the log, restart the service, and collect one snapshot now.

Get helpWhat to send us so that we do not have to ask for more details.