# 42601 — 语法错误（syntax_error）

> PostgreSQL SQLSTATE 42601（语法错误，syntax_error）的源码证据、诊断与处理参考。
---

# 42601 — 语法错误

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

SQLSTATE `42601` 是 Class `42` 中的 **syntax_error**。`42601` 表示语法错误。选定的解析器路径拒绝 `LIMIT 1, 2`，主报文为 `LIMIT #,# syntax is not supported`，提示为 `Use separate LIMIT and OFFSET clauses.`。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `42601` |
| 条件名 | `syntax_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_SYNTAX_ERROR` |
| 别名 | `—` |

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

## 含义 {#meaning}

`42601` 表示语法错误。选定的 `gram.y` 分支在解析阶段拒绝逗号写法，发出 `ERROR` 主报文 `LIMIT #,# syntax is not supported` 和提示 `Use separate LIMIT and OFFSET clauses.` 因此在 PostgreSQL 中逗号写法不是“跳过 1 行再取 2 行”的请求；两个数必须分别写成两个子句。

扫描器和语法分析器共同实现一般的 42601 路径。`scanner_yyerror` 设置 SQLSTATE：当前位置仍有 token 时报告 `syntax error at or near "%s"`，扫描器到达输入缓冲区末尾时报告 `syntax error at end of input`，并附带词法位置。语法动作也可以通过同一格式化路径提供更具体的报文。选定的 LIMIT 分支只是其中一个 producer，并不是所有 `42601` 都必须包含它。

## 诊断 {#diagnosis}

记录完整语句、解析位置、服务器版本和提示。对于 `at or near`，检查 `POSITION` 指向的 token 及其前面的文本；对于 `at end of input`，检查未闭合的引号、美元引号、括号、注释或生成的子句。保留 query builder 实际发送的字节（包括分隔符和替换片段），先把完整语句交给服务器解析，再改变语义。解析器在执行前拒绝该语法，因此选定的自动提交会话仍为 `IDLE`，失败语句不会产生行。在显式事务中，同样的语句级 `ERROR` 会让事务进入失败状态，直到 `ROLLBACK` 或合适的保存点操作；这与选定的自动提交观察是不同的会话边界。不要把语法错误与对象不存在或“已识别但当前上下文不支持”的功能混淆。

## 处理 {#response}

按提示改写语法。对选定的三行有序查询，应把 `LIMIT 1, 2` 改为 `LIMIT 2 OFFSET 1`，结果为 `[2, 3]`；`LIMIT 1 OFFSET 0` 会产生不同结果，不能作为等价修复。生成分页 SQL 的查询构造器应按方言处理。

对于一般扫描器错误，应按位置修复缺失或错放的 token、引号、注释分隔符或 query builder 片段，然后重新解析完整语句。不能因为另一个 42601 也使用同一 SQLSTATE，就套用 LIMIT 改写。

## 报文 {#messages}

选定解析器分支以明确的 `ERROR` 发出主报文 `LIMIT #,# syntax is not supported` 和 HINT `Use separate LIMIT and OFFSET clauses.` 扫描器的固定一般分支使用 `syntax error at or near "%s"` 或 `syntax error at end of input`，位置由词法扫描器生成。LIMIT 主报文/HINT 只能识别选定的分页子路径；只有客户端异常而没有该具体分支的服务器 SQLSTATE 和诊断时，不能识别该子路径，而其他合法 42601 producer 可以有不同主报文。

## 代表案例 {#case}

<!-- BEGIN SQLSTATE SNIPPET: syntax_limit_comma -->

本页使用与运行器注册表相同的语句。执行时，`syntax_schema`、`syntax_role` 等生成名称会替换为一次性实例中的实际值。

```sql
SELECT n FROM generate_series(1, 3) AS s(n) ORDER BY n LIMIT 1, 2;
SELECT n FROM generate_series(1, 3) AS s(n) ORDER BY n LIMIT 2 OFFSET 1;
```

<!-- END SQLSTATE SNIPPET -->

选定的 18.6 运行记录结构化诊断并通过修复断言；10.21 运行通过同一案例的具体检查。可下载的案例和证据投影分别是 [`42601 案例 JSON`](../../data/cases/42601.json) 和 [`作者证据`](../../data/evidence/42601.json)。运行器清单为 `verify/cases/42601/cases.json`，页面 SQL 会与共享注册表核对。

## 版本 {#versions}

选定的自然运行范围是 PostgreSQL 18.6 与 10.21，不能据此推断所有中间版本的行为。

## 相关 {#related}

- [`42602` — 名称无效](../42602/)
- [`42703` — 未定义列](../42703/)

## 来源 {#sources}

- `src.errcodes.18.6` — fixed `errcodes.txt` definition at commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt)).
- `src.limit-comma.18.6` — `src/backend/parser/gram.y` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `7e548b673a1e03eb3a56c5eb9ad92d8e11095fac76e14cb258ca851f58274724` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/parser/gram.y#L13313-L13317)).
- `src.limit-comma.10.23` — `src/backend/parser/gram.y` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `cebad6a5a2bdf68e9e5a4d2e04fa7f5dbf37efac99f5edb73cc661dae1536bad` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/parser/gram.y#L11200-L11204)).
- `src.scanner-syntax.18.6` / `src.scanner-syntax.10.23` — fixed `src/backend/parser/scan.l` `scanner_yyerror` 分支处理 `at end of input` 和 `at or near`；blob SHA-256 `bf453f1ae3c22b84fea6f8e8bed4fda476b7cfa49b234efbf92ca228234d0293` / `a006581a25c659d59b29837010617503ff431f881e3cf0b54a99aa1cc445fe6c` ([18.6 source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/parser/scan.l#L1228-L1240), [10.23 source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/parser/scan.l#L1115-L1127)).
- `src.calls.REL_18_6` / `src.calls.REL_10_23` — fixed call scans, SHA-256 `9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf` / `00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c`.