Docs
文档目录

常见错误速查

按「症状 → 原因 → 处理」速查。只保留 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 缺少必要 scopesConsole → 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 PlatformConsole → 项目 → 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() 401Session 过期或环境切换前端在 account.get() 失败时重定向登录页;确认没有跨 SIT/正式复用 Session

数据库与权限

症状原因处理
所有用户可见所有行,行级权限不生效表未启用 Row Security,或建行时显式传了过宽 permissionscreateTable({ 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 轮询
触发执行报缺 scopecreateExecution 需要 execution.write,不是 functions.writeAPI 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 scopesConsole SDK 只 createEmailPasswordSession 没 setCookie,或误用项目 API KeyConsole 登录后 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

自托管专项

症状原因处理
属性/列状态停在 processingworker-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)

调试技巧