58P03 — file_name_too_long

Source-backed full reference for PostgreSQL SQLSTATE 58P03.

58P03

At a glance

58P03 is selected by PostgreSQL’s file-access errno helper when the saved OS errno is ENAMETOOLONG. It is not a standalone fixed primary such as file name too long: the caller supplies a %m message, and the helper supplies the SQLSTATE.

Field	Value
SQLSTATE	`58P03`
Condition	`file_name_too_long`
Status	`active`
Known present by	`18.0`
Locked snapshots	`18.6, 19beta3`
Macros	`ERRCODE_FILE_NAME_TOO_LONG`
Aliases	`—`

Meaning

errcode_for_file_access() maps ENAMETOOLONG to ERRCODE_FILE_NAME_TOO_LONG. The same complete switch maps ENOENT to 58P01, EEXIST to 58P02, ENOSPC to 53100, and EIO to 58030; all other errno values may map elsewhere. The helper explicitly expects the caller’s primary message to retain %m, so the OS text and locale are part of the useful diagnosis.

Fixed 18.6 backend callers include the base-backup sink’s could not access directory "%s": %m and the tablespace path’s could not set permissions on directory "%s": %m, both emitted with ERROR before the helper chooses the code. These examples show why the operation context matters: the same SQLSTATE can arise from different file operations, while a file-name failure in another caller may carry a different primary template.

Messages

ERROR, representative base-backup primary: could not access directory "%s": %m.
ERROR, representative tablespace primary: could not set permissions on directory "%s": %m.
The %m expansion is the saved OS error text; when it is ENAMETOOLONG, errcode_for_file_access() supplies SQLSTATE 58P03.

There is no fixed source-backed 58P03 primary independent of the caller in this review. Do not replace %m with an invented English sentence or infer an extension’s message from the condition name.

Diagnosis

Capture the complete primary/detail/context, the operation and component, the full path, operating-system errno, filesystem limits, encoding, and any PostgreSQL object-name mapping. Distinguish a filesystem component limit from PostgreSQL’s identifier limits, and distinguish the helper’s ENAMETOOLONG branch from ENOENT, EEXIST, disk-full, and I/O branches. The fixed source confirms the helper and representative callers; it does not claim a natural reproduction on a particular host.

Response

Use a path and name accepted by the owning component and filesystem, or relocate the target while preserving a durable mapping. For a client ERROR in an explicit transaction, ROLLBACK or an existing savepoint is required before continuing; fix the path and retry the affected operation, not arbitrary unrelated statements. A startup/background caller may have no client transaction, and a terminated backend requires a new connection. Preserve the original OS detail when escalating the issue.

Versions

The locked catalogue records 58P03 from 18.0; fixed helper and caller coverage is PostgreSQL 18.6. The page is source-reviewed only and has no natural runtime claim.

58P01, 58P02, 58030