# state_not_found (/docs/reference/errors/state_not_found)

请求中未找到 state 参数。



## 它是什么？ [#它是什么]

在 OAuth 回调过程中，Better Auth 期望在传入请求中存在 `state` 值。
这个 `state` 最初在 OAuth 流程启动时生成，并发送给提供方。当
提供方重定向回你的应用时，它应该在回调请求中包含相同的 `state` 值。如果
回调请求中完全缺少 `state`（查询参数或请求体），我们无法验证流程，请求将被拒绝。

此检查通过确保回调属于发起流程的同一浏览器会话，来防止 CSRF 和重放攻击。

## 常见原因 [#常见原因]

* 你直接导航到了 `/api/auth/callback`，而未先启动 OAuth 流程。
* 反向代理、CDN 或重写规则从回调请求中剥离了查询或请求体参数。
* 授权请求中未向 OAuth 提供方传递 `state`（自定义或手动流程覆盖了参数）。
* 提供方注册的回调 URL 与实际回调路由不匹配，导致中间重定向并丢弃查询或请求体参数。
* 由于框架路由或中间件的原因，回调到达了一个与预期不同的路由/处理程序，且该处理程序没有读取你预期的查询或请求体。
* 移动/WebView 或深度链接交接打开了一个丢失原始查询字符串的新上下文。

## 解决方法 [#解决方法]

### 通过 Better Auth API 启动流程 [#通过-better-auth-api-启动流程]

始终通过 Better Auth 启动 OAuth 流程，以便正确生成并发送 `state`。除非你完整镜像了 Better Auth 的参数，否则请避免直接调用回调端点或构造授权 URL。

### 验证回调 URL 和请求方式 [#验证回调-url-和请求方式]

* 确保提供方配置的回调 URL 与应用的 `/api/auth/callback` 路由完全匹配（包括协议和域名）。
* 大多数提供方通过 GET 和查询参数进行重定向。如果你有自定义处理程序或方法，请确认处理程序读取查询/请求体的方式与提供方的重定向一致。

### 检查代理、重写和中间件 [#检查代理重写和中间件]

* 确认任何反向代理（Vercel、Cloudflare、Nginx）和应用级重写都保留了完整的查询字符串（包括 `state`）。
* 如果有在回调路径上进行重定向或重写的中间件，请确保其完整传递查询和请求体参数。

### 本地调试 [#本地调试]

使用浏览器开发者工具 → 网络面板检查回调请求：

* 确认回调 URL 包含 `?state=...`（或如果期望存在，则请求体中包含 `state`）。
* 确认授权请求之前已在同一会话中发送，并且在重定向回之前存在一个 `state` Cookie。
* 在本地调试期间，在回调处理程序中记录请求查询/请求体字段，以确认服务器实际接收到什么。

### 需要考虑的边缘情况 [#需要考虑的边缘情况]

* 预览环境和生产域名在发生额外重定向或重写时行为可能不同。
* 移动/WebView 环境和深度链接在传递过程中可能丢失或更改查询参数。