PostgreSQL error codes (SQLSTATE) explained
Paste a PSQLException, a log line or a SQLSTATE such as 23505. You get the likely causes in order of frequency, what to check, and read-only SQL to find the culprit. Runs in your browser; we only count anonymous visits.
All errors (43)
23505unique violation
Likely causes, most frequent first
- An insert or update repeats a key that already exists.
- A serial/identity sequence lags behind the data after a restore, import or copy between environments.
- Two requests insert the same key at once, or a retry repeats an insert that had succeeded.
What to check
- Read the DETAIL line: it names the key and the constraint.
- Compare the sequence value with MAX(id).
- Use INSERT … ON CONFLICT where duplicates are expected.
Diagnostic SQL
SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint WHERE conname = 'CONSTRAINT_NAME';
-- sequence behind the data? (example fix: run deliberately)
SELECT setval(pg_get_serial_sequence('table_name','id'), (SELECT MAX(id) FROM table_name));23503foreign key violation
Likely causes, most frequent first
- Inserting or updating a child row whose parent key does not exist.
- Deleting or changing a parent row that still has child rows.
- Rows loaded in the wrong order.
What to check
- Read the DETAIL line: key and table.
- Insert the parent first, delete the children first, or define ON DELETE CASCADE where it is the right rule.
23502not null violation
Likely causes, most frequent first
- A required column is missing from the insert or the application sends null.
- The column has no default.
What to check
- The message names the column; check the mapping or add a default.
23514check violation
Likely causes, most frequent first
- A value outside the rule defined by a CHECK constraint.
What to check
- Show the constraint definition and compare it with the value.
Diagnostic SQL
SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint WHERE contype = 'c' AND conrelid = 'table_name'::regclass;
23P01exclusion violation
Likely causes, most frequent first
- Two rows overlap where an EXCLUDE constraint forbids it (for example overlapping booking ranges).
What to check
- Check the ranges of the new row against existing rows.
22001string data right truncation
Likely causes, most frequent first
- A string longer than the column limit, for example varchar(255).
- Multibyte characters make the string longer than you count.
What to check
- Check the column length and the value; enlarge the column or validate input earlier.
22003numeric value out of range
Likely causes, most frequent first
- A number too large for the column type (integer ids reaching 2,147,483,647 are a classic).
What to check
- Check the column type; move ids to bigint before they run out.
22P02invalid text representation
Likely causes, most frequent first
- A string that does not parse as the target type: integer, uuid, json, boolean, timestamp.
- An empty string sent for a numeric or uuid column.
- Parameters bound in the wrong order.
What to check
- The message shows the offending value; log the parameters.
- Send null instead of an empty string.
22007invalid datetime format
Likely causes, most frequent first
- A date or time string in an unexpected format (day/month order, locale).
What to check
- Send ISO 8601 values or typed parameters instead of strings.
22012division by zero
Likely causes, most frequent first
- A denominator that is zero in some rows.
What to check
- Guard with NULLIF(denominator, 0).
22021character not in repertoire
Likely causes, most frequent first
- A text value containing a NUL byte (0x00), which PostgreSQL text cannot hold.
- Data in another encoding sent as UTF-8.
What to check
- Strip NUL bytes before inserting, and check client_encoding.
2BP01dependent objects still exist
Likely causes, most frequent first
- Other objects (views, constraints, functions) depend on what you drop.
What to check
- Read the DETAIL list; drop dependents first or use CASCADE only if you know what it removes.
25P02in failed sql transaction
Likely causes, most frequent first
- An earlier statement in the same transaction failed and the application kept going.
- An ORM or connection pool swallowed the first error.
What to check
- Find the FIRST error in the log: it is the real cause.
- Roll back after a failure, or use savepoints when you want to continue.
26000invalid sql statement name
Likely causes, most frequent first
- Connection pooling in transaction mode (PgBouncer) hands the next query to a different server connection that never prepared the statement.
What to check
- Disable server-side prepared statements in the driver (for example prepareThreshold=0 in the PostgreSQL JDBC driver), or use session pooling.
- Check the pooler version and its prepared statement support settings.
0A000feature not supported
Likely causes, most frequent first
- The operation is not available in this version or context (for example certain operations on partitioned tables or in a read-only replica).
What to check
- Check the server version and the exact statement; see the release notes.
28000invalid authorization specification
Likely causes, most frequent first
- No rule in pg_hba.conf allows this user, database, address and SSL combination.
- Connecting without SSL where the server requires it, or the reverse.
What to check
- Read the host, user and database shown in the message and compare with pg_hba.conf; reload the configuration after changes.
Diagnostic SQL
SELECT * FROM pg_hba_file_rules;
28P01invalid password
Likely causes, most frequent first
- Wrong password or user name.
- Password changed but the application or secret store still has the old one.
- The user exists in another cluster or environment.
What to check
- Try the credentials with psql against the same host.
- Check the authentication method in pg_hba.conf (scram-sha-256 vs md5 and old drivers).
3D000invalid catalog name
Likely causes, most frequent first
- The database name in the connection string does not exist (typo, wrong environment, not created yet).
What to check
- List databases and compare with the name in your URL.
Diagnostic SQL
SELECT datname FROM pg_database ORDER BY 1;
3F000invalid schema name
Likely causes, most frequent first
- The schema does not exist or the search_path points to it wrongly.
What to check
- Check the schema name and the search_path of the connection.
Diagnostic SQL
SHOW search_path; SELECT schema_name FROM information_schema.schemata;
40001serialization failure
Likely causes, most frequent first
- Concurrent transactions at REPEATABLE READ or SERIALIZABLE conflict; one must be retried.
What to check
- Retry the whole transaction in the application with a small back-off.
- Keep transactions short.
40P01deadlock detected
Likely causes, most frequent first
- Two transactions lock rows in opposite order.
- Foreign keys without an index on the referencing column make parent updates lock more than expected.
What to check
- The server log shows both statements; make code lock in a consistent order.
- Index referencing columns; retry the transaction on this error.
42601syntax error
Likely causes, most frequent first
- A typo, a reserved word used as a name, a missing comma or parenthesis.
- Syntax from another database (LIMIT with TOP, backticks, @ parameters).
- A placeholder style the driver does not support (? vs $1 vs :name).
What to check
- The message points to the token; read the statement just before it.
- Quote reserved words with double quotes or rename.
42702ambiguous column
Likely causes, most frequent first
- A column name that exists in more than one joined table, used without a table alias.
What to check
- Qualify with the table alias.
42703undefined column
Likely causes, most frequent first
- A misspelled column, or one created with quotes and upper-case letters ("UserName") but referenced without quotes.
- The migration that adds the column has not run in this environment.
What to check
- List the table columns and compare, including case.
Diagnostic SQL
SELECT column_name FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'table_name' ORDER BY ordinal_position;
42804datatype mismatch
Likely causes, most frequent first
- An expression of one type assigned to a column of another (text to integer, varchar to jsonb, timestamp to date).
What to check
- Cast explicitly (::type) or send correctly typed parameters.
42883undefined function
Likely causes, most frequent first
- No function matches the name and argument types: usually a missing cast, because the parameter type is unknown.
- An extension that provides the function is not installed in this database.
What to check
- Add a cast to the argument or install the extension (CREATE EXTENSION).
Diagnostic SQL
SELECT extname FROM pg_extension;
42P01undefined table
Likely causes, most frequent first
- The table or view does not exist in the schemas of the search_path.
- Wrong database or schema, or the name was created with quotes in another case.
- The migration has not run.
What to check
- Search the catalog for the name.
- Check search_path and the connected database.
Diagnostic SQL
SELECT table_schema, table_name FROM information_schema.tables WHERE table_name ILIKE 'name'; SHOW search_path;
42P07duplicate table
Likely causes, most frequent first
- CREATE TABLE (or index/sequence) for a name that exists already; a migration ran twice.
What to check
- Use IF NOT EXISTS or check the migration history.
42P18indeterminate datatype
Likely causes, most frequent first
- A parameter used where PostgreSQL cannot infer its type, such as a bare $1 in SELECT or in a function with several overloads.
What to check
- Add a cast to the parameter: $1::text.
42501insufficient privilege
Likely causes, most frequent first
- The user lacks the privilege on the table, schema, sequence or function.
- The privilege was granted on existing objects only; new tables need default privileges.
What to check
- Grant what is needed to the application role, including USAGE on the schema and on sequences.
- Check which role the connection really uses.
Diagnostic SQL
SELECT current_user, session_user;
SELECT has_table_privilege('table_name', 'SELECT');53100disk full
Likely causes, most frequent first
- The data or WAL volume is full.
- WAL accumulates because a replication slot or archive is stuck.
What to check
- Check disk usage, inactive replication slots and archiving.
Diagnostic SQL
SELECT slot_name, active, pg_size_pretty(pg_wal_lsn_diff(pg_current_wal_lsn(), restart_lsn)) AS retained FROM pg_replication_slots;
53200out of memory
Likely causes, most frequent first
- A query uses more memory than available: huge sorts or hash joins with a high work_mem multiplied by many connections.
What to check
- Lower work_mem, add limits, and review the plan.
53300too many connections
Likely causes, most frequent first
- More connections than max_connections: application pools of several instances add up.
- A connection leak.
- Reserved slots are kept for superusers.
What to check
- Count connections by application and state.
- Size each pool so that all instances stay under the limit, or add a pooler such as PgBouncer.
Diagnostic SQL
SELECT application_name, state, COUNT(*) FROM pg_stat_activity GROUP BY 1, 2 ORDER BY 3 DESC; SHOW max_connections;
55P03lock not available
Likely causes, most frequent first
- SELECT … FOR UPDATE NOWAIT/SKIP LOCKED conflict, or lock_timeout expired while waiting for a lock.
- A long-running transaction holds the lock, often an idle one.
What to check
- Find blocking sessions and what they run.
- Commit or end idle transactions; set idle_in_transaction_session_timeout.
Diagnostic SQL
SELECT pid, usename, state, wait_event_type, now() - xact_start AS xact_age, query FROM pg_stat_activity WHERE state <> 'idle' ORDER BY xact_start;
57014query canceled
Likely causes, most frequent first
- statement_timeout expired or the client cancelled the query.
- A conflict with recovery on a standby ("due to conflict with recovery").
What to check
- Check statement_timeout for the role and database.
- Tune the query or run it on a replica configured for long queries.
Diagnostic SQL
SHOW statement_timeout;
57P01admin shutdown
Likely causes, most frequent first
- The server is shutting down or restarting, or an administrator terminated the session.
What to check
- Check restarts and failovers in the server log; make the pool re-validate connections.
57P03cannot connect now
Likely causes, most frequent first
- The server is starting, recovering or in a standby that does not accept connections.
What to check
- Wait and retry; check recovery progress in the log.
08006connection failure
Likely causes, most frequent first
- The connection broke: network drop, firewall idle timeout, server restart.
What to check
- Make the pool validate connections and keep their lifetime below the firewall idle timeout; enable TCP keepalive.
08001sqlclient unable to establish sqlconnection
Likely causes, most frequent first
- Wrong host or port, firewall, the server is not listening on that address (listen_addresses), or the connection limit.
What to check
- Test host and port from the client machine; check listen_addresses and pg_hba.conf.
08003connection does not exist
Likely causes, most frequent first
- Using a connection that was already closed or killed by the server or a proxy.
What to check
- Review pool validation (test query) and connection lifetime settings.
08P01protocol violation
Likely causes, most frequent first
- A driver/server mismatch, a pooler mode that does not support the feature, or a non-PostgreSQL service on the port.
What to check
- Update the driver, check pooler mode and what actually listens on the port.
P0001raise exception
Likely causes, most frequent first
- A PL/pgSQL function or trigger called RAISE EXCEPTION on purpose: the cause is business logic, not a database fault.
What to check
- Read the message text and the function body that raises it.
XX000internal error
Likely causes, most frequent first
- A server bug or corruption-like condition (for example “cache lookup failed for …”, “could not read block”).
What to check
- Look in the server log for the context; update to the latest minor version; for “could not read block” check storage and consider restoring from backup.
How to use this tool
- Paste the exception text. The SQLSTATE codes in it are listed, and common messages such as "duplicate key value violates unique constraint" are recognised even when the code is missing.
- Open an entry and go through the causes from the top.
- Run the diagnostic SQL with a role that can read the catalog and statistics views (pg_stat_activity shows other users' queries only to privileged roles). The queries only read; lines marked as examples change data and are for you to run deliberately.
Example
A Spring application logs current transaction is aborted, commands ignored until end of transaction block (25P02). The entry explains that this is a follow-up error: the real cause is the first error earlier in the log, and the transaction must be rolled back.
Limits
The content is curated from common experience and is not a replacement for the official PostgreSQL documentation or for your server log, which has the exact cause. Messages differ between versions and between drivers. Causes are ordered by how often we see them, not by certainty.
Privacy and security of what you enter
Text you paste is searched in your browser and never sent anywhere. Remove passwords and host names from logs anyway; the log redactor can help. See the privacy notice.
We review Java, PostgreSQL and Oracle setups, connection pools and gateways. See the JVM and pool sizing, the Oracle error explainer or the services.
Message us on LinkedIn