58P03 — file_name_too_long

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.

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

18 19 20

aliases: Unknown
class name: System Error (errors external to PostgreSQL itself)
condition name: file_name_too_long
lang: en
sqlstate: 58P03

Definition PG 18

58P03

At a glance {#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.

Meaning {#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 {#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 {#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 {#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 {#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.

Related {#related}

58P01, 58P02, 58030

Sources {#sources}

src/backend/utils/error/elog.c#L867-L942

src/backend/backup/basebackup_server.c#L119-L124

src/backend/commands/tablespace.c#L606-L618

The structured evidence record records the errno mapping, representative primaries, and source/runtime boundary.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read locked definition snapshot.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "58P03 is file_name_too_long in SQLSTATE Class 58."
}

claims · resolved-paths

{
  "claim_id": "resolved-paths",
  "limits": "The helper establishes the code mapping; it does not fix one primary message for every caller or prove a natural host reproduction.",
  "method": "Read the complete errno switch and representative caller guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.path.1",
    "src.path.2"
  ],
  "statement": "errcode_for_file_access maps ENAMETOOLONG to ERRCODE_FILE_NAME_TOO_LONG and representative backend callers retain %m while emitting ERROR."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use locked catalogue boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 58P03 from 18.0; it does not prove the exact introduction rationale."
}

messages · message.0

{
  "limits": "",
  "message_id": "message.0",
  "path": "",
  "position": 0,
  "raw": {
    "code_selection": "errcode_for_file_access()",
    "id": "message.0",
    "primary_template": "could not access directory \"%s\": %m",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1"
    ],
    "sqlstate": "58P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "could not access directory \" \":",
      "position": 0,
      "role": "",
      "template": "could not access directory \"%s\": %m"
    }
  ]
}

messages · message.1

{
  "limits": "",
  "message_id": "message.1",
  "path": "",
  "position": 1,
  "raw": {
    "code_selection": "errcode_for_file_access()",
    "id": "message.1",
    "primary_template": "could not set permissions on directory \"%s\": %m",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "58P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "could not set permissions on directory \" \":",
      "position": 0,
      "role": "",
      "template": "could not set permissions on directory \"%s\": %m"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L448"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/error/elog.c",
  "position": 1,
  "sha256": "766d30a426ba1d9597657bd46fb890da3e37e4ae53a83d1245bf082ed9433c33",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/error/elog.c#L867"
}

sources · src.path.1

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/backup/basebackup_server.c",
  "position": 2,
  "sha256": "1447d7223926f903d27744605f9caec8a610d78a9f7a7864bb3afb6b3073ac19",
  "source_id": "src.path.1",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/backup/basebackup_server.c#L119"
}

sources · src.path.2

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/commands/tablespace.c",
  "position": 3,
  "sha256": "f0369bece6339d18cd7d4a29b5fa3010447c3b8ece235c64b0d4fbf5f96a5317",
  "source_id": "src.path.2",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/tablespace.c#L606"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:e0ec3ffa05c398032d9d50ddbdd5191c83daa657cd37fbebd1ca5cb4e4802bf0

Text language: en · english-manuals:e0ec3ffa05c398032d9d50ddbdd5191c83daa657cd37fbebd1ca5cb4e4802bf0