# 58030 — io_error

> PostgreSQL SQLSTATE 58030 的源码核验与诊断参考。
---

# 58030

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

`58030` 由共享缓冲区的一条特定清理路径发出：此前已经记录过写入失败，18.6 中该路径报告的是 `WARNING`，不是笼统的客户端 `ERROR`；消息保留数据块和关系对象信息，并提示重复失败可能是永久性的。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `58030` |
| 条件名 | `io_error` |
| 状态 | `有效` |
| 已知存在于 | `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_IO_ERROR` |
| 别名 | `—` |

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

## 含义 {#meaning}

`FlushBuffer` 启动共享缓冲区写入；永久关系会先刷新 WAL，然后调用 `smgrwrite`。异常展开进入缓冲区 I/O 的资源所有者回调时，`AbortBufferIO` 将缓冲区标为 `BM_IO_ERROR`。如果缓冲区仍有效且为脏页，并且这不是第一次失败，它以 `WARNING` 和 SQLSTATE `58030` 报告，再以错误标记结束缓冲区 I/O。较早的 `smgrwrite` 失败才可能使客户端语句失败；后面的警告是重复失败通知，本身不能证明客户端事务已进入错误状态。

关系文本由缓冲区标记通过 `relpathperm` 生成；共享缓冲区写入的错误上下文还可能是 `writing block %u of relation "%s"`。因此它指出排查位置，但不保证只有该数据块受影响。

另一个存储管理器路径用 `FileWrite` 扩展关系段。如果该调用返回负值，`md.c` 以 `ERROR` 报告 `could not extend file "%s": %m` 并调用 `errcode_for_file_access()`；保存的 errno 为 `EIO` 时映射到 `58030`，为 `ENOSPC` 时映射到 `53100`。这个原始 `ERROR` 可能使客户端语句失败并令显式事务进入失败状态；它与 `AbortBufferIO` 后续重复失败的 `WARNING` 是不同的发出路径。

## 消息 {#messages}

- **WARNING**，SQLSTATE `58030`：`could not write block %u of %s`
  - DETAIL：`Multiple failures --- write error might be permanent.`
- 共享缓冲区写入周边的错误上下文：`writing block %u of relation "%s"`。
- **ERROR**，SQLSTATE 由 `errcode_for_file_access()` 选择；保存的 errno 为 `EIO` 时为 `58030`：`could not extend file "%s": %m`
  - HINT：`Check free disk space.`

第一次写失败可能有不同的主消息和 SQLSTATE，例如由 OS errno 辅助函数选择的代码。应把第一次记录与该警告一起保留。在扩展关系的路径中，`EIO` 明确选择该条件，而 `ENOSPC` 选择 `53100`；不能把这些 errno 分支都压成笼统的磁盘已满诊断。

## 诊断 {#diagnosis}

保留完整错误链、第一次写错误、该 warning、日志上下文、关系 fork 和数据块、文件系统/设备 errno、挂载状态，以及 WAL 或副本是否确认写入。确认是后端语句、检查点、后台写进程还是其他服务器路径；源码核验不能代替特定部署的存储定位。

## 处理 {#response}

存储路径不健康时停止重试，检查挂载、设备、权限、空间/配额及存储日志，并在修复前保留关系与副本证据。扩展关系的 `ERROR` 可能令显式客户端事务失败，继续发 SQL 前先 `ROLLBACK` 或回到已经建立的保存点；`AbortBufferIO` 的重复失败 `WARNING` 本身不要求客户端回滚，但仍需修复存储并确认持久性。原因修复后仅按幂等边界重试整个工作单元；后端/服务器已停止时使用新连接，并在重放前确认提交状态。

## 版本 {#versions}

锁定目录从 7.4 记录此条件；固定机制和消息角色来自 PostgreSQL 18.6。本源码条目没有诱发自然 I/O 故障。

## 相关 {#related}

[`53100`](../53100/)、[`58P03`](../58p03/)、[`XX001`](../xx001/)

## 来源 {#sources}

[`src/backend/storage/buffer/bufmgr.c#L4307-L4436`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/storage/buffer/bufmgr.c#L4307)

[`src/backend/storage/buffer/bufmgr.c#L6164-L6225`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/storage/buffer/bufmgr.c#L6164)

[`src/backend/storage/smgr/md.c#L512-L519`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/storage/smgr/md.c#L512)

[`src/backend/utils/error/elog.c#L867-L942`](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/error/elog.c#L867)

结构化[证据记录](../../data/evidence/58030.json)保存固定 warning、detail、源码边界和未运行自然故障的事实。