常见错误速查
按「症状 → 原因 → 处理」速查。只保留 2.6.0 适用项;更完整的专题细节走各功能点文档与 skills/ob-agentbase/references/troubleshooting.md。
环境与配置
| 症状 | 原因 | 处理 |
|---|---|---|
Network error / 连不上 | endpoint 配错(用了 Appwrite Cloud 区域端点,或 SIT/正式混用) | 托管 SIT:https://appbuild-sit.oceanbase.com/v1;正式:https://appbuild.oceanbase.com/v1;自托管用实例地址。见 environment.md |
Invalid 'region' param: Value must be one of (default) | 创建项目传了非 default 区域(如 Appwrite Cloud 枚举) | 2.6.0 只有 region: 'default';数据库池用可选 poolTag 表达,见 overview.md |
User unauthorized / Permission denied(服务端调用) | API Key 缺少必要 scopes | Console → Overview → API Keys 编辑该 Key,按最小集合补 scope(如 databases.read/write、users.read/write、teams.read/write;函数执行触发是 execution.write 不是 functions.write) |
| 请求超时 | 网络问题或环境配错 | 核对环境;服务端 SDK 增加超时;连续失败检查实例健康接口 |
认证与 OAuth
| 症状 | 原因 | 处理 |
|---|---|---|
This provider is disabled... | Provider 未在项目启用 | Console → Auth → Providers 启用并填 Client ID/Secret |
Invalid 'success' param: Invalid URI. Register your new client (...) | OAuth success/failure 的 hostname 未注册为 Web Platform | Console → 项目 → Overview → Platforms 添加该 hostname,见 overview.md |
| OAuth 登录成功但仍显示登录页 | 回调 URL 不匹配或 Session Cookie 未落 | 回调 URL 形如 {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId};确认 success 用页面 origin 根路径 |
Argument of type '"github"' is not assignable... | 用字符串代替枚举 | 用 OAuthProvider.Github 等枚举值;Custom OAuth2 用 OAuthProvider.CustomOauth2(2.6.0 内置) |
| IP 访问时 OAuth 后仍回到登录页 | HTTP + IP 场景浏览器限制第三方 Cookie | 改用 localhost 或 SSH 端口转发;或改走 Custom Token / File Token 等不依赖 Cookie 的路径 |
登录后 account.get() 401 | Session 过期或环境切换 | 前端在 account.get() 失败时重定向登录页;确认没有跨 SIT/正式复用 Session |
数据库与权限
| 症状 | 原因 | 处理 |
|---|---|---|
| 所有用户可见所有行,行级权限不生效 | 表未启用 Row Security,或建行时显式传了过宽 permissions | createTable({ rowSecurity: true }) + 表级只授 create("users"),建行时省略 permissions,见 permissions.md |
Invalid permission format | 手拼权限字符串语法错误 | 使用 SDK 的 Permission.read(Role.user(id)) 辅助构造,见 permissions.md |
Client SDK 建行传 Role.label() 报 401(Permissions must be one of: (any, users, user:xxx, ...)) | Client SDK 行级只能授予自己拥有的角色 | label 类角色放表级 permissions;行级改 Role.user(自己) / Role.team(已加入团队) |
updateRow 后原有权限丢失 | updateRow 传 permissions 时是全量替换 | 先读行取 $permissions,合并后再整组提交,见 permissions.md |
建索引报错不能引用 $createdAt | 索引 attributes 只能用显式业务列 | 先建业务时间列(createdAt 等)再建复合索引;查询排序仍可用 $createdAt |
列创建后一直 processing(自托管) | databases worker 未运行或队列积压 | 查 GET /v1/health/queue/databases;检查 worker 容器状态并重启,见下文「自托管」 |
Cannot set default value for required ... | 列同时设 required: true 与 default | 二选一:要么可空带默认,要么必填无默认 |
写库返回 database_storage_limit_exceeded(413) | 项目数据库存储 quota 用尽 | 调整项目 quota 或清理数据;配额模型见 Console 管理面文档 |
存储
| 症状 | 原因 | 处理 |
|---|---|---|
<img> 加载 preview/view 返回 404,文件实际存在 | fileSecurity: true 下权限不足一律返回 404(隐藏存在性);跨域 HTTP 时 <img> 不带 Session Cookie | 不要把 SDK 返回的 URL 直接赋给 <img src>;用 SDK 认证请求取 Blob URL,或由服务端签发短时 File Token,见 storage.md |
storage.getFilePreview() 返回的 URL 打不开 | 该方法只拼 URL 字符串,不经过 SDK 认证层 | 同上:Blob URL 或 File Token |
| 删除他人上传的文件 403 | 文件级 delete 权限只给了上传者 | 团队协作用 Permission.delete(Role.team(teamId)) |
| 上传 413 / 400 | 超过桶 maximumFileSize / 扩展名不在 allowedFileExtensions | 调整桶配置或前端预校验 |
Storage bucket with the requested ID could not be found | 初始化脚本只建了库表,漏了桶 | 初始化清单补桶创建步骤 |
Functions
| 症状 | 原因 | 处理 |
|---|---|---|
执行失败:Internal curl error ... Error Number: 6(DNS 解析失败,自托管常见) | 函数代码用了外部 URL 初始化 Client,沙箱内解析不了 | 优先用运行时注入的 APPWRITE_FUNCTION_API_ENDPOINT,见 functions.md |
同步执行(async: false)总是 408 超时 | 负载均衡 30 秒连接超时 + 冷启动 | 改 async: true + getExecution 轮询 |
| 触发执行报缺 scope | createExecution 需要 execution.write,不是 functions.write | API Key 两个 scope 都勾选 |
| 2.6.0:经 query string 传 Function API Key 失效 | 2.6.0 起 Function API Key 不再接受 query string 传递 | 使用受保护 header(x-appwrite-key)或平台运行时注入的认证路径;避免 URL、日志、代理泄露 |
| 2.6.0:Function/Site 用户安装/构建命令直接失败 | 受限身份安全条件不满足时不再回退为高权限执行 | 修正命令使其在受限身份下可执行;不要尝试关闭受限身份 |
平台与前端
| 症状 | 原因 | 处理 |
|---|---|---|
CORS 403 / blocked by CORS policy | 访问前端的 hostname/IP 未注册 Platform(或 Project ID 配错) | 先核对 projectId,再补注册所有实际访问的 hostname(含内网 IP、Sites 子域);平台管理只能用 Console 账号 Session,不能用项目 API Key |
| 只有 localhost 能访问,换 IP 失败 | 只注册了 localhost | 注册实际 IP;端口不参与匹配 |
createPlatform 报 User (role: guests) missing scopes | Console SDK 只 createEmailPasswordSession 没 setCookie,或误用项目 API Key | Console 登录后 setCookie 再调用,见 overview.md |
改了 .env.local 不生效 | Shell 环境同名变量优先,或 dist/ / Vite 缓存旧值 | env 检查并清理;清 dist、node_modules/.vite 后重启 |
Realtime 频道报 TypeError: xxx is not a function | 频道常量被当函数调用 | Web SDK 用 Channel.tablesdb(db).table(t).row(r) / Channel.files() 构造频道,见 client-sdk/web.md |
自托管专项
| 症状 | 原因 | 处理 |
|---|---|---|
属性/列状态停在 processing | worker-databases 未运行或崩溃 | GET /v1/health/queue/databases 看积压;重启 worker;注意宕机期间的消息可能已被消费,必要时重建资源 |
| Sites 能力不可用 / 限白名单 | _APP_SITES_WHITELIST_EMAILS 控制准入 | 联系运维配置白名单;API Key 场景要求项目 Team 有 owner 角色成员在名单内 |
| Site URL 404 或 301 到 Console 预览 | 部署未 ready/未激活,或用了受保护预览域 | 核对部署状态;用 Proxy.createSiteRule 建 trigger=manual 公开规则 |
| Sites 页面能开但调 API 失败 | Sites 域名未注册 Platform | 把 Sites 完整 hostname 注册为 Web Platform |
| SSR 页面 401/404、Session 建不起来 | Sites 代理不透传 Cookie/Set-Cookie | 认证改 Client Component + Client SDK;服务端读库用 API Key(Site Variable secret: true) |
调试技巧
浏览器控制台验证 Session:
fetch('<endpoint>/v1/account', { headers: { 'X-Appwrite-Project': '<PROJECT_ID>' }, credentials: 'include' })。验证服务端 API Key:用
Users.list()之类只读调用试跑,捕获AgentbaseException看code/type。SDK 类型化错误模型:JS 抛
AgentbaseException(code为 HTTP 状态码、type为服务端错误类型,附原始响应体);Java 抛 checkedio.agentbase.exceptions.AgentbaseException(getCode()/getType()/getMessage())。存储类 404 先查权限再查存在性(
fileSecurity语义),见 storage.md。