# 22009 — invalid_time_zone_displacement_value

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

# 22009

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

固定 `timetz_recv` 二进制输入路径报告 `time zone displacement out of range`，表示 GMT 位移超过支持范围。

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

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

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

## 含义 {#meaning}

已确认的 `timetz_recv` guard 会把收到的 GMT 位移与 PostgreSQL 支持的上限比较；这是二进制输入契约错误，不是一般 session `TimeZone` 设置错误。

## 报文 {#messages}

已确认的 guard 以 `ERROR` 严重性报告 primary：`time zone displacement out of range`。该源码路径没有固定 DETAIL 或 HINT。本页只有源码证据，没有自然运行观察。

## 诊断 {#diagnosis}

保留实际收到的 offset 数值，检查提供该值的二进制 `timetz` 接收器或协议解码器，区分位移越界、一般 datetime 字段越界和 session `TimeZone` 设置问题。

## 处置 {#response}

在提供该值的客户端或二进制输入边界校验并替换位移；只有输入契约支持时才改用具有预期语义的命名时区。这是 `ERROR`：显式事务中要回滚整个事务，或回滚到失败转换前建立的保存点后再继续。本页没有运行案例。


## 版本 {#versions}

锁定目录从 7.4 记录该条件，并在列出的正式快照及 19beta3 中出现；固定源码覆盖为 PostgreSQL 18.6。

## 相关条件 {#related}

[`22000`](../22000/), [`22001`](../22001/), [`22003`](../22003/), [`22004`](../22004/)

## 来源 {#sources}

详见结构化的[证据记录](../../data/evidence/22009.json)，其中列出固定源码链接与范围限制。