On cPanel/WHM servers running JetBackup 5, account backups that include PostgreSQL databases can finish as partially completed. Home directories, email, SSL certificates, and even PostgreSQL users may back up successfully, while the databases fail with JetBackup PostgreSQL connection errors that look like authentication problems.

The typical message is:

[ERROR] PostgreSQL Error occurred: Failed connecting postgresql server with the provided authentication details

That wording is often misleading. In production, the failure is frequently not a wrong customer database password. It is usually a mix of cPanel’s default pg_hba.conf rules around IPv6 (::1) and samerole, an unsuitable /root/.pgpass host pattern, and sometimes a database map that points at the server’s public IP while PostgreSQL only listens on localhost.

This guide explains the root cause, how to confirm it, and a durable configuration-side fix.

Environment where this failure appears

A JetBackup queue log may look like this:

Databases Backup
[ERROR] PostgreSQL Error occurred: Failed connecting postgresql server with the provided authentication details
Database Users Backup
	* Engine "PostgreSQL"
	- Database User "example_main"
Backup Partially Completed

Database users appearing in the log does not mean the database dump succeeded.

What causes JetBackup PostgreSQL connection errors

1) localhost prefers IPv6 (::1)

On modern Linux, localhost often resolves to ::1 first, then 127.0.0.1.

cPanel’s PostgreSQL pg_hba.conf commonly includes a rule similar to:

host samerole all  ::1/128      md5

samerole only allows a connection when the requested database name matches a role relationship for the connecting user. When JetBackup connects as the postgres superuser to a customer database such as example_app, that rule often does not match.

If there is no broader IPv6 rule, PostgreSQL rejects the connection:

FATAL:  no pg_hba.conf entry for host "::1", user "postgres", database "example_app"

You can reproduce this outside JetBackup:

# Fails on many cPanel servers
pg_dump -h localhost -U postgres -d example_app --schema-only

# Succeeds
pg_dump -h 127.0.0.1 -U postgres -d example_app --schema-only

cPanel documents this JetBackup / ::1 / samerole interaction and lists a workaround:

• cPanel: Jetbackup dumping PostgreSQL may fail – FATAL: no pg_hba.conf entry for host "::1"

JetBackup’s FAQ mainly covers a related but different class of issues (SCRAM vs MD5 / PHP libpq):

• JetBackup 5.4 FAQ – PostgreSQL connection failures

2) Misleading authentication error text

JetBackup often wraps the real PostgreSQL error as “Failed connecting postgresql server with the provided authentication details.” That message can appear even when:

• the password in /root/.pgpass is correct
• psql / pg_dump work against 127.0.0.1
• the real failure is no pg_hba.conf entry or a refused connection to the wrong host

Always correlate PostgreSQL’s own log under /var/lib/pgsql/data/log/ with the JetBackup queue timestamp.

3) /root/.pgpass wildcards can break host selection

cPanel stores the PostgreSQL superuser password for tooling in /root/.pgpass. JetBackup reads that file during account backups.

A common auto-generated style is:

*:*:*:postgres:YOUR_PASSWORD

That wildcard form can make credential helpers resolve an undesirable hostname. In one production case, tooling surfaced 127.0.0.200 (cPanel’s PAM session address) or another non-ideal target before a usable dump connection was established.

A safer explicit form is:

localhost:5432:*:postgres:YOUR_PASSWORD

Optionally also keep:

127.0.0.1:5432:*:postgres:YOUR_PASSWORD
/var/run/postgresql:5432:*:postgres:YOUR_PASSWORD

Avoid relying only on *:*:*:postgres:... when troubleshooting JetBackup 5 PostgreSQL backup failure cases.

4) Account DB maps pointing at the public IP

cPanel stores per-account database ownership maps in:

/var/cpanel/databases/<username>.json

For local PostgreSQL, healthy maps usually look like:

"PGSQL": {
  "server": 0,
  "dbs": {
    "example_app": 0
  }
}

If an account map points at the server’s public IP instead, and PostgreSQL listens only on localhost-style addresses (for example 127.0.0.200, localhost), connections to the public IP are refused. JetBackup may again report a generic authentication-style failure.

How to diagnose the failure quickly

Step A — Confirm JetBackup’s exact failure

Inspect the account queue log under:

/usr/local/jetapps/var/log/jetbackup5/queue/

Focus on the Databases Backup section.

Step B — Reproduce with pg_dump

export PGPASSFILE=/root/.pgpass

pg_dump -h localhost -U postgres -d DBNAME --schema-only >/dev/null
echo $?

pg_dump -h 127.0.0.1 -U postgres -d DBNAME --schema-only >/dev/null
echo $?

If localhost fails and 127.0.0.1 works, you are looking at the IPv6 / pg_hba class of problem behind many JetBackup PostgreSQL connection errors.

Step C — Inspect pg_hba.conf and listen addresses

grep -vE '^[[:space:]]*#|^[[:space:]]*$' /var/lib/pgsql/data/pg_hba.conf
grep -E '^listen_addresses' /var/lib/pgsql/data/postgresql.conf

Step D — Inspect /root/.pgpass shape (do not print passwords)

awk -F: '{print $1,$2,$3,$4,"pass_len="length($5)}' /root/.pgpass

Step E — Inspect the account DB map

python3 - <<'PY'
import json
print(json.load(open('/var/cpanel/databases/USERNAME.json'))['PGSQL'])
PY

Step F — Correlate PostgreSQL logs

grep -E 'no pg_hba|password authentication failed|FATAL' /var/lib/pgsql/data/log/postgresql-*.log | tail

The durable fix for cPanel PostgreSQL backup failures

Apply production changes carefully. Back up config files first.

Fix 1 — Allow JetBackup dumps over IPv6 localhost

Edit /var/lib/pgsql/data/pg_hba.conf and add this line at the bottom:

host all all ::1/128 md5

This matches the workaround published by cPanel for the JetBackup / ::1 / samerole issue.

Optional hardening for local superuser dumps:

host all postgres 127.0.0.1/32 md5
host all postgres 127.0.0.200/32 md5

Reload or restart PostgreSQL:

/scripts/restartsrv_postgresql
# or
systemctl reload postgresql

Restart JetBackup:

systemctl restart jetbackup5d

Fix 2 — Normalize /root/.pgpass

Keep permissions strict:

chmod 600 /root/.pgpass

Use explicit localhost targeting rather than only wildcards:

localhost:5432:*:postgres:YOUR_PASSWORD

If /var/lib/pgsql/.pgpass exists, keep it in sync with the same password. If you change the PostgreSQL password, prefer WHM (SQL Services → Configure PostgreSQL), then verify that /root/.pgpass still uses an explicit localhost host entry.

Fix 3 — Correct local DB maps that point to the public IP

For accounts whose /var/cpanel/databases/<user>.json shows a public IP for PGSQL.server / database hosts, change them to local (0), matching other healthy PostgreSQL accounts on the same server:

"PGSQL": {
  "owner": "example",
  "server": 0,
  "dbs": {
    "example_app": 0
  },
  "dbusers": {
    "example_main": {
      "server": 0,
      "dbs": {
        "example_app": 0
      }
    }
  }
}

Then refresh cPanel DB caches if needed:

/scripts/update_db_cache

How to verify JetBackup PostgreSQL backups after the fix

1. Confirm dump over localhost now works:

export PGPASSFILE=/root/.pgpass
pg_dump -h localhost -U postgres -d DBNAME --schema-only >/tmp/db_schema.sql
echo $?

1. Run an account backup in JetBackup for an affected account.

1. Confirm the queue log contains the database name and no PostgreSQL connection error:

Databases Backup
	* Engine "PostgreSQL"
		- Database "example_app"
Database Users Backup
	* Engine "PostgreSQL"
	- Database User "example_main"
Backup Completed

A healthy result should say Backup Completed, not Backup Partially Completed, unless some unrelated item still fails.

Official status and practical takeaway

So the practical production response to JetBackup PostgreSQL connection errors remains configuration-side: pg_hba.conf, .pgpass host selection, and correct local DB mapping.

Operational checklist

• pg_dump -h localhost works for the affected database
• host all all ::1/128 md5 exists in pg_hba.conf
• PostgreSQL reloaded / restarted after pg_hba changes
• JetBackup restarted after the change
• /root/.pgpass uses explicit localhost (not only *:*:*)
• Affected /var/cpanel/databases/*.json maps use local (0) for local PostgreSQL
• JetBackup account backup shows the PostgreSQL database name with no connection error
• Result is Backup Completed

Conclusion

If JetBackup 5 on cPanel reports PostgreSQL authentication failures during account backups, do not stop at the error string. Test localhost versus 127.0.0.1, inspect pg_hba.conf for the ::1 + samerole pattern, verify /root/.pgpass host targeting, and confirm the account’s PostgreSQL map is local. In many cases, those three checks explain why backups are only partially completed and why customer PostgreSQL databases never make it into the destination snapshot.