error fix

n8n Postgres Connection Error: Internal DB vs Postgres Node Fixes

A Postgres connection error in n8n can come from the self-hosted n8n database settings or from a workflow Postgres node credential; first separate infrastructure database errors from workflow node errors.

Match your incident first

Start with the symptom you can prove

Jump to checks

n8n will not start after setting DB_TYPE=postgresdb

First check: Check DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_DATABASE, DB_POSTGRESDB_USER, DB_POSTGRESDB_PASSWORD, DB_POSTGRESDB_PORT, and DB_POSTGRESDB_SCHEMA in the n8n runtime.

Wrong fix to avoid: Do not change N8N_ENCRYPTION_KEY or wipe the n8n volume while debugging a database connection error.

Verify: n8n starts cleanly and existing workflows and credentials are still visible after a restart.

getaddrinfo ENOTFOUND postgres or connect ECONNREFUSED 127.0.0.1:5432

First check: From the same container or worker that runs n8n, resolve the Postgres host and confirm the port is reachable.

Wrong fix to avoid: Do not expose Postgres publicly just to make localhost work from Docker.

Verify: The n8n runtime can resolve the database host and a tiny SELECT 1 check succeeds from that network path.

password authentication failed for user

First check: Confirm whether the failing credential is n8n's internal database env vars or a workflow Postgres credential, then verify the intended user and database name.

Wrong fix to avoid: Do not switch the workflow to a Postgres superuser to make the error disappear.

Verify: The least-privilege user connects to the intended database and can run the exact low-risk query needed by the workflow.

Use when: self-hosted, Postgres, n8n workflows
First check: Separate whether n8n itself cannot start or only a workflow Postgres node cannot connect.
Time to check: 5-10 minutes
Next step: Match the symptom, then run the verification checks.

Independent third-party notes. n8n is a trademark of its owner and is referenced only for compatibility and troubleshooting context.

Quick Answer

Does this match your symptom?

Postgres connection or query path is failing

n8n cannot reach Postgres, a Postgres node fails in production, or self-hosted database settings are mixed up with workflow credentials.

First check: Separate whether n8n itself cannot start or only a workflow Postgres node cannot connect.

Problem Pattern

The user sees a Postgres connection failure but may be debugging the wrong layer: n8n's own database connection or a workflow Postgres node.

Version awareness

Last reviewed 2026-05-26

Applies to: self-hosted n8n, Docker, Postgres node, queue mode, Postgres
Official docs checked: n8n Supported Databases, n8n Postgres credentials, n8n Postgres Node, n8n Queue Mode
Version-sensitive assumptions: n8n database environment variables, credential UI labels, SSL options, and queue mode defaults can change between releases; confirm against your installed version before changing production.
What may change after upgrades: Credential fields, SSL behavior, database driver defaults, Docker image defaults, and queue worker expectations may shift after n8n upgrades.

Key Facts

Two contexts: Postgres can be n8n's own database or a database accessed by a workflow node.
Self-hosted variable: n8n uses DB_TYPE=postgresdb and DB_POSTGRESDB_* variables for its own database.
Workflow node: The Postgres node uses its own database credentials.
Queue mode: Postgres is recommended for serious queue-mode deployments.

Production Diagnostic Matrix

Turn checks into a brief

Exact symptom or log	Likely cause	First check	Wrong fix to avoid	Verification
n8n will not start after setting DB_TYPE=postgresdb	One of the internal database variables is missing, points at the wrong host, or uses a database user without schema permissions.	Check DB_TYPE, DB_POSTGRESDB_HOST, DB_POSTGRESDB_DATABASE, DB_POSTGRESDB_USER, DB_POSTGRESDB_PASSWORD, DB_POSTGRESDB_PORT, and DB_POSTGRESDB_SCHEMA in the n8n runtime.	Do not change N8N_ENCRYPTION_KEY or wipe the n8n volume while debugging a database connection error.	n8n starts cleanly and existing workflows and credentials are still visible after a restart.
getaddrinfo ENOTFOUND postgres or connect ECONNREFUSED 127.0.0.1:5432	The host value is being resolved from inside the n8n container or worker, where localhost is not the Postgres service.	From the same container or worker that runs n8n, resolve the Postgres host and confirm the port is reachable.	Do not expose Postgres publicly just to make localhost work from Docker.	The n8n runtime can resolve the database host and a tiny SELECT 1 check succeeds from that network path.
password authentication failed for user	The workflow Postgres node is using the wrong credential, a rotated password, the wrong database user, or the internal n8n database credential by mistake.	Confirm whether the failing credential is n8n's internal database env vars or a workflow Postgres credential, then verify the intended user and database name.	Do not switch the workflow to a Postgres superuser to make the error disappear.	The least-privilege user connects to the intended database and can run the exact low-risk query needed by the workflow.
permission denied for schema, table, or sequence	The user can connect but lacks the specific schema, table, sequence, read, or write privilege required by the operation.	Run a minimal query against the exact schema and table the workflow uses, not only SELECT 1.	Do not grant broad database admin privileges before identifying the missing privilege.	The credential can perform only the intended read or write operation and fails on unrelated tables or schema changes.
SSL required, self-signed certificate, no pg_hba.conf entry, or certificate verify failed	The provider requires SSL, the SSL mode in the Postgres credential is wrong, or certificate validation settings do not match the database policy.	Check the provider's SSL requirement, the n8n Postgres credential SSL setting, and any CA file or reject-unauthorized setting used for n8n's internal database.	Do not disable SSL or certificate validation as a permanent production fix without a documented provider-specific reason.	The connection succeeds with the provider-required SSL mode and still targets the intended database and user.
Works manually but fails only in active executions or queue workers	Production executions run on a different worker, network path, image version, or environment than the manual test.	Compare the main process and worker database-related env vars, Postgres credential version, network access, and n8n image tag.	Do not edit SQL before proving the production runtime can reach the same database with the same credential.	A real active execution handled by the production runtime completes the same low-risk Postgres check.

Recommended Steps

Identify whether n8n itself fails to start or only a workflow Postgres node fails.
For n8n's own database, check DB_TYPE and DB_POSTGRESDB_* variables.
For a workflow node, test the Postgres credential and connection settings.
Confirm host, port, database name, user, password, SSL, and schema.
Check database network access from the n8n container or worker.

Verification

n8n starts without database connection errors.
The Postgres node can perform a low-risk SELECT query.
Queue workers can also reach the same database if queue mode is enabled.

First Commands / Checks

Run a low-risk Postgres connectivity check Use from a private terminal when database connectivity is the suspected failure.

psql "postgresql://n8n_app:REDACTED@postgres:5432/n8n" -c "select 1;"

Secrets note: Keep the real password and private host out of tickets, screenshots, and browser pages.
Verification: The command returns one row with value 1, or the error clearly says auth, DNS, SSL, or permission.

Safe Copyable Config

Docker Compose with Postgres for n8n data Use when SQLite is no longer enough or when planning queue mode later.

services:
  postgres:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=n8n
      - POSTGRES_USER=n8n_app
      - POSTGRES_PASSWORD=REDACTED_CHANGE_ME
    volumes:
      - postgres_data:/var/lib/postgresql/data

  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      - DB_TYPE=postgresdb
      - DB_POSTGRESDB_HOST=postgres
      - DB_POSTGRESDB_DATABASE=n8n
      - DB_POSTGRESDB_USER=n8n_app
      - DB_POSTGRESDB_PASSWORD=REDACTED_CHANGE_ME
      - N8N_ENCRYPTION_KEY=REDACTED_GENERATE_ONCE
      - WEBHOOK_URL=https://automation.example.com/
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  postgres_data:
  n8n_data:

What to change: Generate a strong database password and N8N_ENCRYPTION_KEY privately. Back up both Postgres and n8n binary data storage.
Secrets to keep private: POSTGRES_PASSWORD DB_POSTGRESDB_PASSWORD N8N_ENCRYPTION_KEY
Verification: n8n starts without migration errors. A restart preserves workflows and credentials decrypt successfully.
Common mistakes: Changing N8N_ENCRYPTION_KEY after credentials exist. Backing up only the n8n volume while the database holds production state.

Warnings

Do not expose Postgres publicly as a shortcut for container networking problems.
A workflow Postgres node credential is separate from the database n8n uses internally.

Common Mistakes

Using localhost inside a container when the database is another container or host.
Mixing up n8n internal database settings with Postgres node credentials.
Missing SSL settings required by a managed database provider.
Granting insufficient permissions for schema or trigger operations.

Examples

Context split Use this to avoid debugging the wrong layer.

n8n will not start: check DB_TYPE and DB_POSTGRESDB_* variables
Only one workflow fails: check Postgres node credentials
Queue workers fail: check worker environment and database network access

Docker networking check Most self-hosted Postgres failures are host-name or network-scope mistakes.

Database is another Compose service: use the service name, not localhost
Database is on the host machine: use a host address reachable from the container
Database is managed: confirm firewall allowlist, SSL mode, host, port, database, and user
Queue mode: repeat the check from both main and worker containers

Managed database SSL split Use this when credentials are correct but the node still cannot connect.

Authentication failed -> check user, password, database, and permissions
Connection refused or timeout -> check host, port, firewall, and container network
SSL required or certificate error -> check provider SSL mode and certificate requirements
Schema/table missing -> check search path and grants

FAQ

Why does localhost fail from Docker?

Inside a container, localhost usually means the container itself. Use the correct Compose service name, host gateway, or network address for the database.

Do queue workers need the same database settings?

Yes. Workers need access to the same database and compatible environment configuration.

Sources

n8n Supported Databases Accessed 2026-05-08 n8n Postgres Node Accessed 2026-05-08 n8n Postgres credentials Accessed 2026-05-26 n8n Queue Mode Accessed 2026-05-08