38000 — external_routine_exception

Class 38 is broad. Fixed PostgreSQL 18.6 paths include external command failures in COPY ... PROGRAM and basebackuptoshell, UUID library failures, and exceptions propagated from PL/Perl, PL/Python, and PL/Tcl. These are separate implementations under one category.

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

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: External Routine Exception
condition name: external_routine_exception
lang: en
sqlstate: 38000

Definition PG 18

38000

At a glance {#at-a-glance}

Class 38 is broad. Fixed PostgreSQL 18.6 paths include external command failures in COPY ... PROGRAM and basebackup_to_shell, UUID library failures, and exceptions propagated from PL/Perl, PL/Python, and PL/Tcl. These are separate implementations under one category.

Meaning {#meaning}

Representative messages include program "%s" failed and shell command "%s" failed, each with an internal wait-status detail; OSSP uuid library failure: %s, OSSP uuid library failure: error code %d, uuid library failure: %d, and the UUID version-mismatch message; PL/Perl reports such as didn't get a return item from function, PL/Python forwards %s with optional detail/context/hint, and PL/Tcl reports could not parse function return value: %s or a context-bearing %s. Keep the dynamic fields and the actual producer; this category has no single fixed message.

Messages {#messages}

Diagnosis {#diagnosis}

Use the message and context to identify the external boundary: program path and wait result, UUID library operation, or PL language and routine. Inspect the relevant server configuration and handler logs, preserving dynamic %s values and any internal detail.

Response {#response}

Repair the named external command, library, or language routine and verify that boundary independently. A failed external action may have side effects; do not replay it until completion and idempotency are known.

Versions {#versions}

The locked catalogue places this condition at least by PostgreSQL 7.4. The facts block lists the published snapshots; source-path status is limited to the fixed PostgreSQL 18.6 evidence below.

Related {#related}

38001, 2F000

Sources {#sources}

Read the fixed basebackup_to_shell.c, copyto.c, uuid-ossp.c, plperl.c, and pltcl.c paths alongside the structured evidence record.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read the fixed errcodes definition row, severity, and macro.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "38000 is external_routine_exception in SQLSTATE Class 38."
}

claims · resolved-path

{
  "claim_id": "resolved-path",
  "limits": "Source confirmation is not a runtime observation in this batch.",
  "method": "Read the complete source context around the resolved report groups.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.path.0",
    "src.path.1",
    "src.path.2",
    "src.path.3",
    "src.path.4",
    "src.path.5",
    "src.path.6"
  ],
  "statement": "The fixed PostgreSQL 18.6 source contains the external-command, UUID-library, and PL/Perl, PL/Python, PL/Tcl report contexts and message variants described on the page."
}

claims · history-boundary

{
  "claim_id": "history-boundary",
  "limits": "Definition presence is not an emitting-path observation.",
  "method": "Compare canonical release facts with the available history boundary.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "Locked release definitions establish catalogue presence from 7.4; they do not establish a precise introducing release or runtime use."
}

messages · message.basebackup-shell-failed

{
  "limits": "The command and internal wait-status detail are dynamic.",
  "message_id": "message.basebackup-shell-failed",
  "path": "",
  "position": 0,
  "raw": {
    "detail_template": "%s",
    "id": "message.basebackup-shell-failed",
    "limits": "The command and internal wait-status detail are dynamic.",
    "primary_template": "shell command \"%s\" failed",
    "severity_source": "ERROR",
    "sources": [
      "src.path.0"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.0"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "shell command \" \" failed",
      "position": 0,
      "role": "",
      "template": "shell command \"%s\" failed"
    },
    {
      "kind": "detail",
      "literal": "",
      "position": 1,
      "role": "",
      "template": "%s"
    }
  ]
}

messages · message.copy-program-failed

{
  "limits": "The program path and internal wait-status detail are dynamic.",
  "message_id": "message.copy-program-failed",
  "path": "",
  "position": 1,
  "raw": {
    "detail_template": "%s",
    "id": "message.copy-program-failed",
    "limits": "The program path and internal wait-status detail are dynamic.",
    "primary_template": "program \"%s\" failed",
    "severity_source": "ERROR",
    "sources": [
      "src.path.1",
      "src.path.4"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.1",
    "src.path.4"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "program \" \" failed",
      "position": 0,
      "role": "",
      "template": "program \"%s\" failed"
    },
    {
      "kind": "detail",
      "literal": "",
      "position": 1,
      "role": "",
      "template": "%s"
    }
  ]
}

messages · message.uuid-library-text

{
  "limits": "The external UUID library text is interpolated into the primary message.",
  "message_id": "message.uuid-library-text",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.uuid-library-text",
    "limits": "The external UUID library text is interpolated into the primary message.",
    "primary_template": "OSSP uuid library failure: %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "OSSP uuid library failure:",
      "position": 0,
      "role": "",
      "template": "OSSP uuid library failure: %s"
    }
  ]
}

messages · message.uuid-library-code

{
  "limits": "The external UUID status code is dynamic.",
  "message_id": "message.uuid-library-code",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.uuid-library-code",
    "limits": "The external UUID status code is dynamic.",
    "primary_template": "OSSP uuid library failure: error code %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "OSSP uuid library failure: error code",
      "position": 0,
      "role": "",
      "template": "OSSP uuid library failure: error code %d"
    }
  ]
}

messages · message.uuid-library-code-short

{
  "limits": "The UUID library status value is dynamic; this branch is used by the uuid-ossp fallback path.",
  "message_id": "message.uuid-library-code-short",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.uuid-library-code-short",
    "limits": "The UUID library status value is dynamic; this branch is used by the uuid-ossp fallback path.",
    "primary_template": "uuid library failure: %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "uuid library failure:",
      "position": 0,
      "role": "",
      "template": "uuid library failure: %d"
    }
  ]
}

messages · message.uuid-version-mismatch

{
  "limits": "The UUID version character is dynamic.",
  "message_id": "message.uuid-version-mismatch",
  "path": "",
  "position": 5,
  "raw": {
    "id": "message.uuid-version-mismatch",
    "limits": "The UUID version character is dynamic.",
    "primary_template": "uuid_create() produced a version %c UUID instead of the expected version 1",
    "severity_source": "ERROR",
    "sources": [
      "src.path.2"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.2"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "uuid_create() produced a version UUID instead of the expected version 1",
      "position": 0,
      "role": "",
      "template": "uuid_create() produced a version %c UUID instead of the expected version 1"
    }
  ]
}

messages · message.plperl-no-return-item

{
  "limits": "",
  "message_id": "message.plperl-no-return-item",
  "path": "",
  "position": 6,
  "raw": {
    "id": "message.plperl-no-return-item",
    "primary_template": "didn't get a return item from function",
    "severity_source": "ERROR",
    "sources": [
      "src.path.5"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.5"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "didn't get a return item from function",
      "position": 0,
      "role": "",
      "template": "didn't get a return item from function"
    }
  ]
}

messages · message.plpython-forwarded-diagnostics

{
  "limits": "PL/Python forwards the underlying dynamic message and optional DETAIL, CONTEXT, and HINT; no single static primary template is asserted.",
  "message_id": "message.plpython-forwarded-diagnostics",
  "path": "",
  "position": 7,
  "raw": {
    "dynamic_format": "errmsg_internal %s; errdetail_internal %s; errcontext %s; errhint %s",
    "id": "message.plpython-forwarded-diagnostics",
    "limits": "PL/Python forwards the underlying dynamic message and optional DETAIL, CONTEXT, and HINT; no single static primary template is asserted.",
    "primary_template": null,
    "severity_source": "caller-selected level",
    "sources": [
      "src.path.3"
    ],
    "sqlstate": "38000"
  },
  "severity": "caller-selected level",
  "sources": [
    "src.path.3"
  ],
  "templates": []
}

messages · message.pltcl-return-parse

{
  "limits": "The parse error text is dynamic.",
  "message_id": "message.pltcl-return-parse",
  "path": "",
  "position": 8,
  "raw": {
    "id": "message.pltcl-return-parse",
    "limits": "The parse error text is dynamic.",
    "primary_template": "could not parse function return value: %s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.6"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "could not parse function return value:",
      "position": 0,
      "role": "",
      "template": "could not parse function return value: %s"
    }
  ]
}

messages · message.pltcl-context

{
  "limits": "Both error text and function name are dynamic.",
  "message_id": "message.pltcl-context",
  "path": "",
  "position": 9,
  "raw": {
    "context_template": "%s\nin PL/Tcl function %s",
    "id": "message.pltcl-context",
    "limits": "Both error text and function name are dynamic.",
    "primary_template": "%s",
    "severity_source": "ERROR",
    "sources": [
      "src.path.6"
    ],
    "sqlstate": "38000"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "",
      "position": 0,
      "role": "",
      "template": "%s"
    },
    {
      "kind": "context",
      "literal": "in PL/Tcl function",
      "position": 1,
      "role": "",
      "template": "%s\nin PL/Tcl function %s"
    }
  ]
}

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#L300"
}

sources · src.path.0

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/basebackup_to_shell/basebackup_to_shell.c",
  "position": 1,
  "sha256": "4f42cb76243182416e6c4ca50029ab82c794d297ae36759f57511f18ff110b43",
  "source_id": "src.path.0",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/basebackup_to_shell/basebackup_to_shell.c#L239"
}

sources · src.path.1

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

sources · src.path.2

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "contrib/uuid-ossp/uuid-ossp.c",
  "position": 3,
  "sha256": "b09f5fb48b28df9c279780181d2f3410e34a29904eba298b93ab9166aaa8a8e4",
  "source_id": "src.path.2",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/uuid-ossp/uuid-ossp.c#L387"
}

sources · src.path.3

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/pl/plpython/plpy_elog.c",
  "position": 4,
  "sha256": "707d4948e22451e4013abaf961e5dfd8b9573d709f5a47fb7e879587106cd8bf",
  "source_id": "src.path.3",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/plpython/plpy_elog.c#L123"
}

sources · src.calls.REL_18_6

{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "",
  "path": "raw/calls/REL_18_6.jsonl",
  "position": 5,
  "sha256": "9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf",
  "source_id": "src.calls.REL_18_6",
  "tag": "",
  "url": ""
}

sources · src.path.4

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/commands/copyto.c",
  "position": 6,
  "sha256": "f160930f5821d7320f3ac686f4edc4a7b341f84697ee5200eeff352f331c0bd5",
  "source_id": "src.path.4",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/copyto.c#L575"
}

sources · src.path.5

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/pl/plperl/plperl.c",
  "position": 7,
  "sha256": "90789190fd0bf5b53773b57b8c3287c88c35fbebdfa8310acab3f2d89910e4ba",
  "source_id": "src.path.5",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/plperl/plperl.c#L2250"
}

sources · src.path.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/pl/tcl/pltcl.c",
  "position": 8,
  "sha256": "cd9c06395a4bb6125bda553a6ecdeebdcc7922e6a12ddb84c98c0c3d1d39a172",
  "source_id": "src.path.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/tcl/pltcl.c#L1036"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:1541096bc4abbd389339b87503cfd2d206c478730cad698bb9659796a041d5d3

Text language: en · english-manuals:1541096bc4abbd389339b87503cfd2d206c478730cad698bb9659796a041d5d3