PostgreSQL Invalid Name (SQLSTATE 42602)

PostgreSQL raises ERROR: invalid name with SQLSTATE 42602 and condition name invalid_name when a SQL identifier — such as a table name, column name, function name, or parameter name — contains characters that are not permitted or otherwise fails PostgreSQL's naming rules. This error belongs to the 42 error class ("Syntax Error or Access Rule Violation").

What This Error Means

SQLSTATE class 42 covers syntax and access rule violations. Code 42602 specifically signals that an identifier in the SQL statement is syntactically malformed — not merely that the object is missing, but that the name itself cannot be a legal SQL identifier under PostgreSQL's rules.

PostgreSQL identifiers follow strict rules: they must begin with a letter (a–z, including non-ASCII letters) or an underscore, and subsequent characters may be letters, digits, underscores, or dollar signs ($). Quoted identifiers (delimited by double quotes) allow almost any character, but even quoted identifiers have some restrictions — for example, they cannot be zero-length (an empty string "" is not a valid identifier).

When PostgreSQL's parser encounters a name that violates these rules before the query reaches the planner or executor, it raises 42602. The transaction is not necessarily aborted by this error alone, but the statement that triggered it fails immediately and any surrounding transaction is left in its pre-statement state (or in an error state if there was an active transaction block, requiring a ROLLBACK before further commands are issued).

Common Causes

1. Zero-length (empty) quoted identifier. Using "" as a table or column name is not valid even inside double quotes. PostgreSQL explicitly disallows empty identifiers.

2. Null byte in an identifier. An identifier containing a null byte (\0) cannot be processed by the parser and triggers 42602.

3. Dynamic SQL constructing a malformed name. Application code that builds identifiers programmatically (e.g., via string concatenation) can produce names with leading digits, spaces without quoting, or disallowed special characters before the name is passed to PostgreSQL.

4. PL/pgSQL or server-side function using an invalid variable or parameter name. Declaring a variable or parameter with a name that starts with a digit or contains a disallowed character raises this error at function-creation time.

5. Type or operator name construction in extensions. Some extensions or CREATE TYPE / CREATE OPERATOR statements that supply a name component programmatically can generate this error if the computed name is invalid.

How to Fix invalid_name

1. Avoid empty identifiers. Replace any occurrence of "" in your SQL with a real name. An empty string is never a valid SQL identifier.

   -- Wrong: empty identifier
   SELECT "" FROM my_table;
   
   -- Correct: use a real column name
   SELECT id FROM my_table;
   

2. Quote identifiers with unusual characters using double quotes, and ensure the name is non-empty and contains no null bytes.

   -- Identifier with spaces: must be double-quoted
   CREATE TABLE "my table" (id serial PRIMARY KEY);
   
   -- Referencing it later
   SELECT * FROM "my table";
   

3. Sanitize dynamically constructed identifiers in application code. If your application builds SQL with dynamic object names, use the driver's quoting/escaping facility or PostgreSQL's built-in quote_ident() function — and validate that the raw name is not empty before passing it.

   -- In PL/pgSQL: use quote_ident() to safely construct dynamic SQL
   DO $$
   DECLARE
     tbl_name text := 'my_table';
     query    text;
   BEGIN
     IF tbl_name = '' THEN
       RAISE EXCEPTION 'Table name must not be empty';
     END IF;
     query := 'SELECT count(*) FROM ' || quote_ident(tbl_name);
     EXECUTE query;
   END;
   $$;
   

4. Fix PL/pgSQL variable names that start with a digit or contain invalid characters. Variable and parameter names in PL/pgSQL follow the same identifier rules as SQL.

   -- Wrong: variable name starts with a digit
   CREATE OR REPLACE FUNCTION bad_func() RETURNS void AS $$
   DECLARE
     1st_value integer;  -- invalid name
   BEGIN
   END;
   $$ LANGUAGE plpgsql;
   
   -- Correct: prefix with a letter or underscore
   CREATE OR REPLACE FUNCTION good_func() RETURNS void AS $$
   DECLARE
     first_value integer;
   BEGIN
   END;
   $$ LANGUAGE plpgsql;
   

5. Check ORM or migration tool output for generated names. Some ORMs auto-generate column or table names based on model field names. If your model field has a value that produces an invalid SQL identifier, the ORM may pass it through without quoting. Inspect the raw SQL being sent to PostgreSQL (enable query logging or use log_min_duration_statement = 0) to see the offending identifier.

Additional Information

• SQLSTATE 42602 is part of error class 42 (Syntax Error or Access Rule Violation). Related codes in the same class include 42601 (syntax_error), 42622 (name_too_long), and 42939 (reserved_name).
• The name_too_long error (42622) is a close sibling: PostgreSQL limits identifiers to 63 bytes by default (controlled by the compile-time NAMEDATALEN constant). Names exceeding this limit are silently truncated in most contexts, but in some contexts PostgreSQL raises 42622 instead.
• Most PostgreSQL client drivers (libpq, psycopg, asyncpg, JDBC) surface 42602 as a server-side error with the SQLSTATE preserved. Check ProgrammingError (Python), PSQLException (Java/JDBC), or the equivalent in your driver.
• This error is raised at parse time, so it cannot be deferred and will never appear inside a BEGIN/COMMIT block without immediately aborting the current statement. Issue a ROLLBACK before retrying if you are inside a transaction.

Frequently Asked Questions

Why does PostgreSQL allow almost any character in a double-quoted identifier, yet still raise 42602? Double-quoted identifiers greatly relax the character restrictions compared to unquoted identifiers, but two things remain disallowed even inside double quotes: an empty string and any identifier containing a null byte (\0). If you hit 42602 with a quoted identifier, check for these two cases.

My ORM generated SQL that causes 42602 — how do I find the bad identifier? Enable PostgreSQL query logging temporarily (log_min_duration_statement = 0 in postgresql.conf or SET log_min_duration_statement = 0 for your session) and reproduce the error. The log will show the exact SQL statement sent to the server, making it easy to spot the offending identifier.

Can 42602 appear during a migration or schema change? Yes. Migration tools that generate CREATE TABLE, ALTER TABLE, or CREATE INDEX statements with dynamically constructed names (e.g., index names built from table and column names) can produce invalid identifiers if the source names contain special characters or result in an empty string after transformations.

Is 42602 retryable? No. The error is deterministic — the same SQL statement will always fail with 42602 until the identifier is corrected. Retrying without fixing the SQL will not help. Fix the identifier in the query or in the code that generates it.