Browse articles

Database backup

# The database connection test failed. What is wrong?

An error status is usually caused by dump tools missing from the PATH, a wrong host or port, credentials or user privileges, or database access rules. Here is how to check.

2 min readUpdated: October 22, 2026[Baca dalam Bahasa Indonesia](/help/uji-koneksi-gagal)

When a connection is saved or the **test** button is clicked, the agent on the server tries to connect to the database. If it fails, the connection status becomes **error** and the error message is shown on the server page.

## Common causes

-   **Client tools are not on the PATH**: the agent uses `mysql`/`mysqldump`, `psql`/`pg_dump`, or `mongodump`/`mongosh`. Install the client package that matches your database server version.
-   **Wrong host or port**: a database on the same server is usually `localhost` or `127.0.0.1`. For a database in a container or on another server, enter an address reachable from the agent's server.
-   **Wrong username or password**, or the user has no access to the selected database.
-   **Database access rules**: for example `pg_hba.conf` in PostgreSQL or `bind-address` in MySQL rejecting connections from the agent's address.
-   **MySQL 8 with a MariaDB client**: the client must support the `caching_sha2_password` plugin.
-   **The agent is offline**: the test only runs while the agent is online; while offline the status stays _pending_.

## Test manually from the server

Run the same test with the database tools on the agent's server:

```bash
mysql -h 127.0.0.1 -P 3306 -u backup -p -e "SELECT 1"
psql "host=127.0.0.1 port=5432 user=backup dbname=shop" -c "SELECT 1"
mongosh "mongodb://backup@127.0.0.1:27017/shop" --eval "db.runCommand({ ping: 1 })"
```

If the manual test fails too, fix it on the database side first. If it succeeds, click **test** again in the dashboard.

## Changing a connection's password

Connections cannot be edited yet. If the password is wrong or has changed, delete the connection and add it again with the correct password. Remember that deleting a connection also deletes the jobs that use it, so note the job settings before deleting.

## See also

-   [Connecting a database](/docs/koneksi-database)
-   [Agent offline](/help/agent-offline)

Still need help?

Open a support ticket from the dashboard and our team will reply as soon as possible.

[Browse the docs](/en/docs)[Open a ticket](/app/support/new)