Installation problems

This page covers the installation itself: the messages the install command stops with, and the setup page in your browser while the installation runs. Entries that follow a change on your server say what changed, so you know where you stand before you run anything again.

The install command runs in a shell on the server that runs PostgreSQL, as root or from an account that can use sudo. The setup page is the page in Guardioz that shows the command and the state of the installation: open Servers, click + Add server, and then Self-Managed PostgreSQL.

Two things help you read the output. The installer prints every step as it goes, and during the registration step it shows the agent’s own messages, each beginning with the date, the time, the level and [guardioz-agent]. The quotes on this page show the message without that prefix. The examples use the port 5432. Replace 5432 with the port of your PostgreSQL instance.

When the server is registered and no data arrives afterwards, see Agent and data problems.

The installation ended with errors

What you see

On Linux, the last lines are similar to the following:

=== Setup finished with errors ===

  Registered instances: 0

On FreeBSD the heading is always === Setup finished ===, whether or not an instance was registered.

Why it happens

The installer reports each step for the instance it registers. The heading only summarises the run, so do not judge the run by the heading. The line that counts is Registered instances:. When it reads 0, no instance was registered, and the installer ends with exit code 1. When it reads 1, the server is registered and the installer ends with exit code 0, also under the heading === Setup finished with errors ===.

On Linux the heading reads === Setup finished with errors === in two cases only: the registration failed, or the agent’s service did not come up running under its own system account. Other failures do not change the heading. Most of them stop the installer before the summary, with an error message and a non-zero exit code. A few are reported in the output while the run goes on, for example an access entry on the data directory that could not be set.

Check

Scroll back to the line that starts with --- Instance: on Linux, or --- Instance on port on FreeBSD. The lines under it belong to that instance, and one of them names the cause.

Fix

Find that message on this page. Entries for a message the installer prints on your server say what it had already changed at that point.

The setup page keeps showing Waiting for server registration…

What you see

The status line under the install command stays on Waiting for server registration…. The page shows no error, because it has no failure state and no expiry state: it waits.

Why it happens

Guardioz has not received a registration for this command. There are three usual reasons:

• The installer stopped. The terminal has the reason, and the page never will.
• The command ran on a machine that cannot reach https://app.guardioz.com/, or on a machine other than the one that runs PostgreSQL.
• The page was reloaded, or opened in a second tab, after you copied the command. Every load creates a new command and follows only that one. The command you copied still works for its 60 minutes, but this tab never changes.

Check

Read the terminal output first. Then open Servers in Guardioz: a registered server is listed there whatever the setup page shows.

Fix

Decide from the terminal, not from the browser tab. When the terminal ended with === Setup complete! ===, the installation is done and the server is under Servers. Otherwise find the installer’s message on this page.

The setup page keeps showing Server registered, installing agent…

What you see

The status line stays on Server registered, installing agent… and never reaches Agent installed and running!. The card Setup complete! does not appear, and the browser does not move on by itself.

Why it happens

Your server is registered, and the registration step also sends its first snapshot. What is missing is the installer’s last message, which it sends only after it confirms that the agent’s service runs. The installer sends that message once and does not repeat it, so a lost request leaves the page here even when the service runs.

Check

Read the last lines at the terminal, and then the state of the service on the server. See Check that the agent works.

Fix

Open Servers. The server is listed there, with the results of its first snapshot when that snapshot arrived. When the terminal reports that it did not arrive, the entry The initial snapshot did not reach the cockpit applies. When the service does not run, the entry The agent’s service did not start says what to do. Do not run the install command again for this: a new run needs a new command and gives the monitoring role a new password.

Registration failed with a message about the setup token

What you see

One of these lines, followed by Registration failed.:

Registration failed (HTTP 401): Setup token has expired

Registration failed (HTTP 409): Setup token has already been used

Registration failed (HTTP 401): Invalid setup token

Why it happens

An install command carries a one-time token. It is valid for 60 minutes and works once.

• Expired: more than 60 minutes passed between the moment the setup page created the command and the moment the installer sent the registration.
• Already used: this command already registered a server.
• Invalid: the token that reached Guardioz is not one it knows, for example after a partial paste.

Check

The line before Registration failed. carries the reason.

Fix

In Guardioz, open Servers, click + Add server, click Self-Managed PostgreSQL, and then click Copy command. Run that command to the end, in a shell on the server that runs PostgreSQL, as root or from an account that can use sudo. Copy it with the button instead of typing it, and do not reuse a command from your shell history.

After the fix

The setup page moves to Server registered, installing agent… and then to Agent installed and running!.

Registration failed because the plan has no place for another server

What you see

This line, followed by Registration failed.:

Registration failed (HTTP 403): The Free plan includes 3 servers, and this organization already has 3, so the server was not registered. Delete a server that you no longer monitor, or write to contact@guardioz.com about a larger plan, and then add this server again.

The plan and the two numbers are those of your organization: the Team plan includes 5 servers.

Why it happens

Each plan includes a number of servers: 3 on the Free plan, 5 on the Team plan, and no limit on the Scale plan. Guardioz counts the servers of your organization when a new server registers, and it refuses a server beyond the limit before it writes anything. The limit applies only to registration: Guardioz keeps checking every server that is already registered, also when your organization has more servers than its plan includes, so the limit never stops a registered server from being checked. Running the installer again on a server that is already registered is not counted as a new server when the agent’s configuration file for that port still names the same Guardioz address and holds a working key for a server of your organization. Otherwise the run counts as a new server.

Check

In Guardioz, open Servers, click + Add server, and then click Self-Managed PostgreSQL. The page shows a line such as Servers: 3 of 3 on the Free plan.

Fix

Delete a server that you no longer monitor (see Delete a server), or write to contact@guardioz.com about a larger plan. Then run the same install command again. A refusal for the plan does not use up the install command, so it still works while its 60 minutes last. After that, take a new command from the setup page.

The installer set up the server before Guardioz refused it: it created or changed the monitoring role and installed the agent. When this server already had a working agent, see the next entry.

After the fix

The setup page moves to Server registered, installing agent… and then to Agent installed and running!.

Registration failed because the account is disabled

What you see

Registration failed (HTTP 403): The account that created this install command is disabled, so the server was not registered. Contact us to have it reopened.

Why it happens

Guardioz has switched off the account that created the install command, so it registers no server for it. The installer set up the server before Guardioz refused it, as in the next entry.

Fix

Write to contact@guardioz.com from the address of the account. See Get help.

The agent stopped collecting after a refused install command

What you see

The install command ended with Registration failed. on a server that already had a working agent, and no new snapshot arrives. Above that line the installer printed the reason, for example a refusal from Guardioz that begins with Registration failed (HTTP, or Connection failed: when the registration request did not reach Guardioz. The agent’s log reports a collection error once per interval:

Error during collection cycle

Under that line stands the traceback of the error, and its last line names what PostgreSQL answered.

Why it happens

The installer gives the monitoring role a new password before it sends the registration. When Guardioz then refuses the registration, or the request does not reach it, the agent’s configuration file still holds the previous password, so the running agent can no longer log in to PostgreSQL. It keeps trying once per interval.

Check

Read the agent’s log on that server. See Check that the agent works.

Fix

Take a fresh command from the setup page. Run it to the end in a shell on that server, as root or from an account that can use sudo. It sets a new password, writes the matching configuration file and restarts the service.

The run connects to the same server and keeps its history when the configuration file for that port still names the same Guardioz address, and still holds a working key for a server of your organization. What a re-run changes, and how it differs from an update: Update the agent.

After the fix

The registration step sends a snapshot at once, so Snapshot sent (HTTP 202) stands in the installer’s output at that step, before it installs the service.

The installer stops without choosing a PostgreSQL instance

What you see

On a server with more than one PostgreSQL 18 instance, one of these messages:

Error: this server runs 2 PostgreSQL 18 instances, and one install command
registers one of them. This run has no terminal to ask which one.

Error: GUARDIOZ_PORT is set to "5434", which is not the port of a PostgreSQL 18
instance on this server.

Error: no answer came from the terminal.

Each one continues with the instances you can choose from and with a hint:

The PostgreSQL 18 instances on this server that Guardioz can register:
    port 5432
    port 5433
To choose one without a question, run the same install command again with its end
changed from '| bash' to '| env GUARDIOZ_PORT=<port> bash', for example:
    ... | env GUARDIOZ_PORT=5432 bash

No Guardioz files were installed, no monitoring role was created or changed,
pg_hba.conf was not changed, and no packages were installed or updated.
If you need help, write to contact@guardioz.com and tell us which system this is.

On FreeBSD the hint names sh instead of bash.

Why it happens

One install command registers one PostgreSQL instance, and the installer changes only the instance it registers. When it finds more than one PostgreSQL 18 instance, it asks on the terminal of your session which one to register. It stops instead of choosing for you in three cases:

• The run has no terminal to ask on, for example in a script or a configuration-management tool.
• GUARDIOZ_PORT holds a port that no PostgreSQL 18 instance on this server uses.
• The input ended before a number was entered, for example after Ctrl+D.

Check

The last lines of the message say that nothing was installed or changed. The command registered nothing, so it is still unused while it is valid.

Fix

Run the same command again in a terminal where you can type, and enter the number of the instance at the question. Or choose the instance in advance with GUARDIOZ_PORT, as the hint shows. The exact command for each system is in Install on Linux and Install on FreeBSD. When the command has expired, take a fresh one from the setup page.

A server with more than one PostgreSQL instance is not supported: see Requirements. If you need Guardioz on such a server, write to contact@guardioz.com and tell us about the server.

After the fix

The installer prints Registering the instance on port 5433., or Registering the instance on port 5433, chosen with GUARDIOZ_PORT., and continues with that instance only.

The installer stops and reports that it needs administrator rights

What you see

One of these messages:

Error: this run needs administrator rights, this account is not root, and sudo
was not found on this system.
Run this command as root, or ask an administrator of this server to run it.

Error: this run needs administrator rights, and sudo did not grant them.
Run this command as root, or ask an administrator of this server to run it.

Error: sudo refused a check that runs without asking for a password.
This run has no terminal for sudo to ask on, so Guardioz stops here instead of
failing part-way through.
Run this command as root, or from a terminal where sudo can ask.

Each of them ends with:

No Guardioz files were installed, no monitoring role was created or changed,
pg_hba.conf was not changed, and no packages were installed or updated.
If you need help, write to contact@guardioz.com and tell us which system this is.

Why it happens

The installer creates a database role, installs files and installs a service, so it needs administrator rights. It settles them before it changes anything. The first message means that your account is not root and the server has no sudo. The second means that sudo refused. The third means that the run has no terminal for sudo to ask for a password on. That is what happens in automation, and in a command started as ssh HOST 'COMMAND'. The message then also replays what sudo itself reported.

Check

In a shell on that server, show the name of your account:

id -un

Then check whether sudo runs a command for this account without asking for a password. This is the first check the installer makes:

sudo -n true

The command prints nothing when sudo runs commands for this account without a password. When it prints sudo: a password is required, confirm that the account can use sudo with its password:

sudo -v

The command asks for your password and prints nothing more when the account can use sudo. It prints a refusal when the account cannot.

Fix

Run the install command as root, or in an interactive session from an account that can use sudo. The command carries no sudo of its own: the installer works out per step which rights it needs.

After the fix

The run goes on past the check of administrator rights, and later prints a line that begins with Detecting PostgreSQL.

Error: cannot connect to PostgreSQL.

What you see

Error: cannot connect to PostgreSQL.
Tried: psql as ACCOUNT on port 5432, psql as OWNER on port 5432.
Make sure PostgreSQL is running and you have access.

ACCOUNT is the account you ran the command from, and OWNER is the account that owns the cluster. When the PGUSER environment variable is set, the list starts with psql -U and the role that it names. The line lists every port the installer tried. The message is the same on Linux and on FreeBSD.

Why it happens

The installer first finds the PostgreSQL instances that run on this machine and the port of each. On each of those ports it tries the role named in the PGUSER environment variable, then the role with the name of your own account, then the account that owns the cluster. When it finds no running instance, it tries port 5432. The account that owns the cluster connects with its own settings: the installer does not pass the PG variables of your session, such as PGUSER, to it. None of the attempts connected. There are three usual reasons:

• PostgreSQL does not run on this machine.
• The command ran on a machine other than the one that runs PostgreSQL.
• The instance uses a socket directory other than the one the installer connects through.

Guardioz supports the default socket directory: /var/run/postgresql on Linux and /tmp on FreeBSD. An instance whose socket lives somewhere else is not supported.

Check

First confirm that PostgreSQL runs on this machine. In a shell on that server, list the PostgreSQL services and their state:

systemctl list-units 'postgresql*' --no-pager

On Debian and Ubuntu, pg_lsclusters also lists each cluster with its port and state. On FreeBSD, use service postgresql status instead.

When PostgreSQL runs and you can still reach it as the account that owns the cluster, show the socket directories in an SQL session on that instance:

SHOW unix_socket_directories;

When the answer names a directory other than /var/run/postgresql on Linux or /tmp on FreeBSD, Guardioz does not support this instance today. Write to contact@guardioz.com.

Fix

Start PostgreSQL, run the install command on the server that runs it, and make local connections possible for one of the accounts the installer tries. Nothing on the server was changed at this point, and your install command is not used up.

Error: Guardioz connected to PostgreSQL, but no account it can use may create a role.

What you see

Error: Guardioz connected to PostgreSQL, but no account it can use may create a role.
Accounts that connected: postgres on port 5432.
Guardioz creates a read-only monitoring role, so it stops here instead of installing
files it could not finish configuring.
Run this command as an account that can create roles, or grant CREATEROLE to one of
the accounts above.

The second line lists the accounts that connected on your server, each with the port of the instance it connected to.

On a server with more than one PostgreSQL instance, this message can also come right after you chose the instance to register. The installer chooses its account on the first instance where one works, and when you choose another instance, it asks the same question there before it changes anything. It prints this line first:

  Checking the connection on port 5433, the instance to register...

Why it happens

The installer creates the read-only monitoring role guardioz_monitor, so the role it connects with has to be a superuser or have CREATEROLE. It confirms that before it installs anything, on the instance it registers, because a role that can only connect would fail later, with files already on the server.

Check

In an SQL session opened as one of the accounts the message lists, ask whether that role can create a role:

SELECT rolsuper OR rolcreaterole FROM pg_roles WHERE rolname = current_user;

The answer is t when this role can create the monitoring role, and f when it cannot.

Fix

Run the install command from an account whose PostgreSQL role is a superuser, for example postgres.

A role that has CREATEROLE and nothing more passes this check, and then cannot give the monitoring role the pg_monitor permission that Guardioz reads with. The installer reports that permission as granted either way, so parts of the collection stay empty afterwards. How to confirm the permission and grant it: One dataset or one database is missing from the results.

Nothing on the server was changed, and your install command is not used up.

The installer cannot run commands as the account that owns the cluster

What you see

Error: Guardioz could not run commands as postgres, the account that owns this
PostgreSQL cluster. This is a permissions problem on this server, not a problem
with PostgreSQL.

or:

Error: Guardioz switched to postgres, the account that owns this PostgreSQL
cluster, but could not run psql as that account. PostgreSQL itself was not
contacted.
Install the PostgreSQL client tools, or make psql reachable for that account, and
run this command again.

The messages name the account that owns your cluster. The first one also replays what the attempt reported.

Why it happens

To reach PostgreSQL, the installer can switch to the account that owns the cluster. The first message means that the switch was refused, by the sudo policy, or by the account’s own shell or login settings. The second means that the switch worked and psql is not reachable for that account.

Check

From an account that uses sudo, confirm the switch:

sudo -u postgres psql -p 5432 -c "SELECT 1;"

When you ran the install command as root, the installer uses runuser or su instead. Confirm it with this command:

runuser -u postgres -- psql -p 5432 -c "SELECT 1;"

Replace postgres with the account that owns your cluster.

Fix

For the first message, run the install command as root, or from an account whose sudo policy allows commands to run as the account that owns the cluster. For the second, install the PostgreSQL client tools for that account, or make psql reachable for it. Nothing on the server was changed.

The installer reports that Guardioz supports PostgreSQL 18 only

What you see

  Guardioz supports PostgreSQL 18 only. Its data collection, checks and
  recommendations are built and verified against PostgreSQL 18, so it does not
  monitor another version. These instances are not registered:
...

  Nothing was installed and nothing on this server was changed.
  Move the instance to PostgreSQL 18 and run this command again.

Between the two parts, the installer lists each instance it did not register, with its version and its port. The last two lines appear when no PostgreSQL 18 instance is left. On FreeBSD the third line reads monitor another version. The instances marked above are not registered. instead.

An instance whose version the installer cannot read is refused as well. On Linux:

  Warning: cannot read the PostgreSQL version on port 5432 - skipping this instance.

On FreeBSD:

  Port 5432: cannot read the PostgreSQL version - this instance is skipped.

When no instance is left, the Linux installer stops with:

Error: no reachable PostgreSQL instances found.

Why it happens

Guardioz supports PostgreSQL 18 only. The installer applies that limit before it changes anything on the server, and Guardioz applies it a second time when the server registers.

Check

In an SQL session on that instance, with any role that can connect:

SHOW server_version;

Fix

Move the instance to PostgreSQL 18, and then run the command again. The PostgreSQL documentation describes the ways to do that: Upgrading a PostgreSQL cluster.

A refusal for the version does not use up the install command, so the same command still works while its 60 minutes last. For an instance whose version cannot be read, make local connections to that instance possible and run the command again.

Error: the PostgreSQL instance on port 5432 is a replica (a standby server).

What you see

Error: the PostgreSQL instance on port 5432 is a replica (a standby server).
       Guardioz does not support replicas. Run the same install command on the
       primary server. In a Patroni cluster, that is the member that
       patronictl list shows as Leader.
No Guardioz files were installed, no monitoring role was created or changed,
pg_hba.conf was not changed, and no packages were installed or updated.
Your install command is not used up.

When the installer cannot tell whether the instance is a replica, the first line reads Error: Guardioz could not read whether the PostgreSQL instance on port 5432 is a, and the message goes on to say that Guardioz stops instead of guessing.

Why it happens

Guardioz supports the primary server only. A replica is read-only, and the installer would have to create the monitoring role and set its password there, which PostgreSQL does not allow. The installer reads the role of the instance before it changes anything, so nothing on the server was changed.

Check

In an SQL session on that instance, with any role that can connect:

SELECT pg_is_in_recovery();

t means that the instance is a replica, and f that it is a primary.

Fix

Run the same install command on the primary server while the command is valid. See Requirements for what Guardioz does after a failover.

Error: psql not found.

What you see

Error: psql not found. Install PostgreSQL client tools first.

Why it happens

The installer searches for its tools in a fixed list of directories: /usr/local/sbin, /usr/local/bin, /usr/sbin, /usr/bin, /sbin and /bin. A command installed outside them is not found.

Check

On that server, show where the command is:

command -v psql

Fix

Install the PostgreSQL 18 client tools, or make psql reachable in one of those directories. Then run the command again. Nothing on the server was changed, and your install command is not used up.

Error: curl, tar, openssl or systemctl not found.

What you see

On Linux, one of these messages, followed by the lines that say what the installer did not change:

Error: curl not found. The installer downloads the agent with it.
       Install curl and run the same install command again.

Error: tar not found. The installer unpacks the agent with it.
       Install tar and run the same install command again.

Error: openssl not found. The installer generates the monitoring role's password with it.
       Install openssl and run the same install command again.

Error: systemctl not found. The agent runs as a systemd service, and Linux without systemd is not supported.
       Run the install command on a server that runs systemd.

The last line is Your install command is not used up.

Why it happens

The installer runs these programs after its first change on the server. It checks that they are installed before that change, so that a missing program stops the run while the server is still untouched. It searches for them in the same fixed list of directories as for psql, described in the previous section. systemctl is part of systemd: the agent runs as a systemd service, so a server without systemd is not supported.

Check

On that server, show where the command is, for example for openssl:

command -v openssl

Fix

Install the program that the message names with your distribution’s package manager, for example the openssl package, and run the same install command again while its 60 minutes last. For systemctl, see Requirements. Nothing on the server was changed.

Error: this server’s python3 is Python 3.10, and the Guardioz agent needs Python 3.11 or newer.

What you see

Error: this server's python3 is Python 3.10, and the Guardioz agent needs
       Python 3.11 or newer.
       The installer looked for: python3 python3.14 python3.13 python3.12 python3.11.
       Install a newer Python next to the system one, with its venv module, and run
       the same install command again. For example:

           Ubuntu 22.04:              sudo apt install -y python3.11 python3.11-venv
           RHEL, Rocky, AlmaLinux 9:  sudo dnf install -y python3.11
...

The version in the first line is the one your python3 has. When the server has no Python at all, the first line is Error: Python 3.11 or newer not found. This message comes from the Linux installer. On FreeBSD the installer installs a fitting Python itself.

Why it happens

The agent needs Python 3.11 or newer. Ubuntu 22.04 ships Python 3.10 as python3, and Red Hat Enterprise Linux, Rocky Linux and AlmaLinux 9 ship Python 3.9. The installer then looks for python3.14, python3.13, python3.12 and python3.11 in the directories listed in the previous section, and it found none of them.

Check

On that server, list the Python versions the installer can find:

for p in python3 python3.14 python3.13 python3.12 python3.11; do command -v $p && $p --version; done

Fix

Install one of the versioned Pythons next to the system one, with the command the message shows for your system, and run the same install command again while its 60 minutes last. Keep the system python3 as it is: the operating system’s own tools use it. Nothing on the server was changed, and your install command is not used up.

Error: Python cannot create virtual environments on this host.

What you see

  Error: Python cannot create virtual environments on this host.
         The venv/ensurepip module is missing. On Debian/Ubuntu, install it
         and then re-run this install command:

             sudo apt update && sudo apt install -y python3-venv
...

The message ends with a second package name that carries a version number, for example python3.13-venv. Use that name when apt reports that python3-venv does not exist. When the installer chose a versioned Python, such as python3.11 on Ubuntu 22.04, the command names that version’s package, for example python3.11-venv, and there is no second name. As root, the message prints the commands without sudo.

Why it happens

On Debian and Ubuntu, python3 ships without the module that creates virtual environments; it lives in its own package. The agent’s Python libraries go into such an environment, so the installer confirms the module before it builds one.

Check

On that server, confirm that the module is there:

python3 -c "import ensurepip, venv"

The command prints nothing when the module is there.

Fix

Install the package that the message names, and then run the same install command again while its 60 minutes last. Otherwise take a fresh command from the setup page.

The installer stops before it changes anything on the server, and the message says so.

After the fix

The installer continues past Installing Guardioz Agent... and prints Agent installed.

Error: the system account for the agent’s service already exists, and its group does not.

What you see

On Linux:

Error: the system account for the agent's service already exists, and its group does not.

On FreeBSD:

Error: the system account for the agent's service already exists, and it is not in its group.

The next lines name the account and give the command that creates the group, or that adds the account to it on FreeBSD. The last lines say that nothing was changed and that your install command is not used up.

Why it happens

The installer creates a system account for the agent’s service, and a group with the same name. When an account with that name already exists, the installer uses it and does not change it, because it can be managed by someone else on this server. The service needs the group as well: on Linux the service runs with that group, and on both systems the agent reads its configuration file through it. An account that exists without that group cannot run the agent, so the installer stops before it changes anything.

Check

On Linux, show the account and the group, in a shell on the server, with the account name from the message in place of ACCOUNT:

getent passwd ACCOUNT
getent group ACCOUNT

On FreeBSD, show the groups of the account:

id -Gn ACCOUNT

Fix

Run the command that the message gives, as root or with sudo, and then run the same install command again while its 60 minutes last. Otherwise take a fresh command from the setup page.

After the fix

The installer goes past this check. On Linux it prints later, after Agent installed., that the account already exists and was left unchanged.

pip stops the installation with an error that begins with ERROR:

What you see

On Linux, after the line Installing Guardioz Agent..., a message from pip, the program that installs Python libraries, that begins with ERROR: and names a library such as psycopg2-binary. The installer stops there, without a summary.

Why it happens

On Linux the installer first installs the agent’s Python libraries into /opt/guardioz-agent/venv from the Python package index, at pypi.org and files.pythonhosted.org. Without outbound HTTPS to those addresses, pip cannot download them. The agent has no proxy setting, and neither does this step of the installer.

Check

On that server, ask the package index for one of the libraries and show the answer code:

curl -fsS -o /dev/null -w '%{http_code}\n' https://pypi.org/simple/psycopg2-binary/

200 means the server can reach the package index. Allow files.pythonhosted.org as well: pip downloads the files from there.

Fix

Allow outbound HTTPS from that server to pypi.org and files.pythonhosted.org for the time of the installation, and run the command again. Nothing in PostgreSQL was changed at this point, and your install command is not used up. The directories /opt/guardioz-agent and /etc/guardioz-agent can already exist; the next run uses them.

Error: Could not download agent source

What you see

  Error: Could not download agent source from https://app.guardioz.com/api/v1/setup/agent-source

On FreeBSD the same message begins with a lower-case could. Or, when the download arrived incomplete:

  Error: agent package is not importable after install (checked /opt/guardioz-agent).

Why it happens

The installer downloads the agent’s code from Guardioz in a second request. The first message means that this request did not finish: the server has no outbound HTTPS connection to https://app.guardioz.com/, something between them blocked it, or Guardioz refused it because too many requests came from this network address in a short time. The agent has no proxy setting, so the server needs a direct outbound connection.

Check

On that server, ask for the same file and show the answer code:

curl -fsS -o /dev/null -w '%{http_code}\n' https://app.guardioz.com/api/v1/setup/agent-source

200 means the server can reach Guardioz. On a server without curl, for example a FreeBSD host, ask for the same file with fetch:

fetch -qo /dev/null https://app.guardioz.com/api/v1/setup/agent-source && echo reachable

Fix

Allow outbound HTTPS from that server to https://app.guardioz.com/, or wait a minute when several servers were installed from one network address at the same time. Then run the command again. Nothing in PostgreSQL was changed at this point, and your install command is not used up.

The monitoring role cannot log in over the local socket

What you see

  Connection failed - updating pg_hba.conf...

and then one of:

  Still cannot connect. Check pg_hba.conf manually: HBA_FILE

  Cannot locate pg_hba.conf. Add this line manually (local socket, read-only user):
      local  all  guardioz_monitor  scram-sha-256

HBA_FILE is the path of the file on your server. The installation goes on, and the registration then fails:

Cannot connect to PostgreSQL at HOSTNAME:5432 (REASON). The server was NOT registered - fix the connection or the monitoring credentials and run the installer again.
  Registration failed.

Why it happens

The agent reads PostgreSQL over the local socket with a password, so the monitoring role has to be able to log in that way. The installer confirms it, and adds two lines to pg_hba.conf when it cannot.

The role still cannot log in afterwards when another rule earlier in the file matches it first, because PostgreSQL uses the first rule that matches. It also cannot log in when the instance uses a socket directory other than the default one.

Check

In an SQL session as a superuser, list the local rules in the order PostgreSQL reads them:

SELECT file_name, line_number, type, database, user_name, auth_method
FROM pg_hba_file_rules
WHERE type = 'local'
ORDER BY line_number;

PostgreSQL uses the first rule whose type, database and user match the connection. A rule whose user_name column holds {all} matches the monitoring role too, so the Guardioz rule has to stand before it. The file_name column names the file to edit.

Fix

Open that file as root or as the account that owns the cluster, and put these two lines in it, before any other local rule that matches the role:

# Guardioz monitoring (read-only, local socket only)
local  all  guardioz_monitor  scram-sha-256

Load the file into the running server, in an SQL session as a superuser:

SELECT pg_reload_conf();

Then run the install command again, to the end. The same command still works while its 60 minutes last, because the registration step gave up before it sent its request. After that, take a fresh command from the setup page. At this point the monitoring role exists with a new password, and the two lines are in the file when the installer found the file.

The agent’s service did not start

What you see

On Linux, after Waiting for agent to start..., the installer reports that the service did not start running as the account it has to run as, and names two commands:

    Check: journalctl -u guardioz-agent-5432 -n 20 --no-pager
    And:   systemctl show -p MainPID -p ActiveState guardioz-agent-5432

On FreeBSD:

  Agent guardioz_agent_5432 did not stay running. Check /var/log/guardioz_agent_5432.log

  Failed to start guardioz_agent_5432. Check /var/log/guardioz_agent_5432.log

Why it happens

The server is registered, and the registration step already sent its first snapshot. When that snapshot did not get through, the terminal reports it, and the entry The initial snapshot did not reach the cockpit applies as well.

What did not start is the service that collects from now on. On Linux the installer confirms both that the service is active and that its process runs under the dedicated account for the agent’s service.

Check

Run the two commands from the message, or read the log file on FreeBSD. Two messages in the log say that the service was started with a configuration file that does not hold what it needs: api_url is not configured and collector_key is not configured.

Fix

See Agent and data problems for what the log reports. The server itself is registered and stands under Servers. Its first results are there when the registration step’s snapshot arrived. The setup page stays on Server registered, installing agent….

After the fix

Right after a start the log carries Waiting 3600s before first collection (registration already sent a snapshot). 3600s is one hour: the agent waits one full interval after every start. To get a snapshot now, run one collection by hand. See Manage the agent service.

The initial snapshot did not reach the cockpit

What you see

The initial snapshot did not reach the cockpit. The server is registered; the agent will collect on its schedule, or run it once to retry now.

In that message, cockpit is the Guardioz web app.

Why it happens

The server is registered, and the snapshot that the registration step sends did not arrive. The lines before it name the reason, for example Connection error (attempt 1/3):, Failed to send snapshot after 3 attempts, or a line that begins with Cockpit refused the snapshot (HTTP. When that line reads Cockpit refused the snapshot (HTTP 429): A snapshot of this server arrived less than 600 seconds ago., the run reconnected a server whose last snapshot came less than 10 minutes before. The service then waits one full interval, one hour as the installer sets it, before its own first collection.

Check

In Guardioz, open Servers. The row for this server shows Last seen Never.

Fix

Allow outbound HTTPS from that server to https://app.guardioz.com/, and then run one collection by hand instead of waiting for the next one, at least 10 minutes after the last snapshot of that server. See Manage the agent service.

After the fix

The log reports Snapshot sent (HTTP 202), and the first results appear on Findings within a few minutes.

Registration failed (HTTP 429): Too many requests

What you see

Registration failed (HTTP 429): Too many requests from this network address. Wait a minute and try again.

The download of the install script can meet the same limit. You then see the error of your download tool, and nothing runs on the server.

Why it happens

Guardioz limits how many requests one network address can send in a short time. The count is per address, so several installations from one office meet that limit together.

Check

The summary reports Registered instances: 0 when this was the only instance of the run.

Fix

Wait a minute and run the same command again: it was not used up. When more than 60 minutes have passed since the setup page generated it, take a fresh command from the setup page.

FreeBSD: the installer cannot get the agent’s Python packages

What you see

Error: the configured pkg repository has no Python version that provides all
       three agent dependencies (psycopg2, pyyaml, requests).
       - Refresh the catalogue and re-run: pkg update -f
       - Check which repository branch this server uses (quarterly vs latest): pkg -vv
       - Or install them manually for one Python version and re-run, e.g.:
         pkg install -y py312-psycopg2 py312-pyyaml py312-requests

or:

Error: could not install Python dependencies via pkg.

From an account that uses sudo, the pkg update and pkg install lines in the message carry sudo in front of them. A third message reports that the packages installed and the Python on the server cannot import them: Error: python cannot import psycopg2/yaml/requests after install.

Why it happens

On FreeBSD the agent’s three Python libraries come from packages, not from pip. The installer asks the package repository which Python version ships all three, and installs that version with them. A stale catalogue, or a repository branch that does not carry all three for one version, ends here.

Check

On that FreeBSD server, show which package repository it uses:

pkg -vv

The output names the repository this server uses.

Fix

Follow the steps in the message, and then run a fresh install command. When you install the three packages by hand, use one Python version for all three.

After the fix

The installer finds them by itself and prints Agent dependencies already available for PYTHON_PATH - skipping package installation., where PYTHON_PATH is the interpreter it will use.

The command does not run: wrong system, or not the command from Guardioz

What you see

The Linux command on a FreeBSD server:

This is the Linux installer, but this host is FreeBSD.
Use the FreeBSD command from the Guardioz setup page (it uses:
  fetch -qo - '<url>/api/v1/setup/install-freebsd.sh?token=...' | sh).

The FreeBSD command on another system:

Error: this is the FreeBSD installer, but the OS is Linux.
       Use the Linux command (curl ... | bash) from the setup page.

A script that did not come from the setup page:

Error: setup token is missing. Generate a new command in Guardioz.

Error: this script was not served by Guardioz (the supported PostgreSQL version is missing).
       Copy the install command from the Guardioz setup page and run it again.

Why it happens

Each of these means that the command which ran is not the one the setup page generated for this operating system. The page shows the Linux command until you click FreeBSD. A script saved from a plain address carries neither the one-time token nor the PostgreSQL version that Guardioz puts into the command it hands you. The Linux command uses curl and bash, and a stock FreeBSD has neither, so on FreeBSD it can end in your shell’s own message instead, such as curl: not found. The FreeBSD command uses fetch, which Linux does not have, so on Linux it usually ends with your shell’s message that fetch is not found, and the installer does not start.

Check

In a shell on that server, show which operating system it runs:

uname -s

Fix

In Guardioz, open the setup page, click Linux or FreeBSD for your system, click Copy command, and run that command. Nothing on the server was changed.

Failed to generate command. Reload the page to try again.

What you see

The setup page shows this sentence where the install command belongs, on both the Linux and the FreeBSD button, and Copy command stays disabled. The line Waiting for server registration… does not appear, because without a command no server can register.

Why it happens

The page asks Guardioz for a command as soon as it opens, and that request did not succeed. The usual reason is that your session is no longer valid. Guardioz also refuses the request when too many came from your network address in a short time.

Check

Open another page in Guardioz, for example Servers. When your session has ended, Guardioz takes you to the sign-in page.

Fix

Sign in again, open Servers, click + Add server, and then Self-Managed PostgreSQL. When the sentence appears again at once, wait a minute and reload the page. For sign-in problems, see Sign-in and email problems.

If your problem is not on this page

• The server is registered and no data or no findings arrive: Agent and data problems.
• You cannot sign in, or the confirmation email did not arrive: Sign-in and email problems.
• You want the list of everything the installer changes: What the installer changes on your server.
• Nothing matches what you see: write to contact@guardioz.com. For what to include, see Get help.