# 38000 — external_routine_exception

> PostgreSQL SQLSTATE 38000 的源码与诊断参考。
---

# 38000

## 速览 {#at-a-glance}

SQLSTATE 38000 是外部例程异常类别。固定的 PostgreSQL 18.6 路径覆盖外部命令、UUID 库和 PL 语言处理器；这些实现必须按各自边界分别诊断。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `38000` |
| 条件名 | `external_routine_exception` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_EXTERNAL_ROUTINE_EXCEPTION` |
| 别名 | `—` |

<!-- source facts: data/errcodes/38000.json -->
<!-- END SQLSTATE FACTS -->

## 含义 {#meaning}

代表性消息包括 `program "%s" failed` 和 `shell command "%s" failed`，二者都带内部 wait-status detail；UUID 路径还会报告 `OSSP uuid library failure: %s`、`OSSP uuid library failure: error code %d`、`uuid library failure: %d` 或 UUID 版本不匹配；PL/Perl 有 `didn't get a return item from function` 等报文，PL/Python 会转发带可选 detail/context/hint 的 `%s`，PL/Tcl 则有 `could not parse function return value: %s` 或带上下文的 `%s`。应保留动态字段和实际产生者；这个类别没有一条固定消息。

## 消息 {#messages}

代表性消息包括 `program "%s" failed` 和 `shell command "%s" failed`，二者都带内部 wait-status detail；UUID 路径还会报告 `OSSP uuid library failure: %s`、`OSSP uuid library failure: error code %d`、`uuid library failure: %d` 或 UUID 版本不匹配；PL/Perl 有 `didn't get a return item from function` 等报文，PL/Python 会转发带可选 detail/context/hint 的 `%s`，PL/Tcl 则有 `could not parse function return value: %s` 或带上下文的 `%s`。应保留动态字段和实际产生者；这个类别没有一条固定消息。

## 诊断 {#diagnosis}

根据消息和 context 确认外部边界：程序路径及等待结果、UUID 库操作，还是 PL 语言和例程。检查相关服务器配置和处理器日志，保留动态 `%s` 值及内部 detail。

## 处理 {#response}

修复消息点名的外部命令、库或语言例程，并独立验证该边界。外部动作失败时可能已经产生副作用；在确认完成状态和幂等性前不要重放。

## 版本 {#versions}

锁定目录将该条件的已知下界记为 PostgreSQL 7.4；事实块列出已发布快照，源码路径状态仅限于下方固定的 PostgreSQL 18.6 资料。

## 相关 {#related}

[`38001`](../38001/), [`2F000`](../2f000/)

## 来源 {#sources}

可直接阅读固定的 [basebackup_to_shell.c](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/basebackup_to_shell/basebackup_to_shell.c#L239-L243)、[copyto.c](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/copyto.c#L575-L579)、[uuid-ossp.c](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/uuid-ossp/uuid-ossp.c#L130-L136)、[plperl.c](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/plperl/plperl.c#L2250-L2264) 和 [pltcl.c](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/pl/tcl/pltcl.c#L1036-L1039) 路径；完整范围和未解决的运行边界见结构化[证据记录](../../data/evidence/38000.json)。