Common Errors Quick Reference
Quick lookup by "symptom → cause → fix". Only 2.6.0 applicable items are kept; for more complete topic details see each feature's documentation and skills/ob-agentbase/references/troubleshooting.md.
Environment and Configuration
| Symptom | Cause | Fix |
|---|---|---|
Network error / cannot connect | endpoint misconfigured (using an Appwrite Cloud region endpoint, or mixing SIT/production) | Managed SIT: https://appbuild-sit.oceanbase.com/v1; production: https://appbuild.oceanbase.com/v1; for self-hosted use the instance address. See environment.md |
Invalid 'region' param: Value must be one of (default) | A non-default region was passed when creating the project (e.g., an Appwrite Cloud enumeration) | 2.6.0 only has region: 'default'; the database pool is expressed with the optional poolTag, see overview.md |
User unauthorized / Permission denied (server-side calls) | API Key is missing required scopes | Console → Overview → API Keys, edit the key and add scopes per the minimal set (e.g. databases.read/write, users.read/write, teams.read/write; function execution triggering requires execution.write, not functions.write) |
| Request timeout | Network issues or misconfigured environment | Verify the environment; add a timeout in the server-side SDK; if failures persist, check the instance health endpoint |
Authentication and OAuth
| Symptom | Cause | Fix |
|---|---|---|
This provider is disabled... | Provider not enabled for the project | Console → Auth → Providers, enable it and fill in the Client ID/Secret |
Invalid 'success' param: Invalid URI. Register your new client (...) | The hostname of the OAuth success/failure is not registered as a Web Platform | Console → project → Overview → Platforms, add the hostname; see overview.md |
| OAuth login succeeds but the login page is still shown | Callback URL mismatch or the session cookie was not set | The callback URL must look like {endpoint}/account/sessions/oauth2/callback/{provider}/{projectId}; confirm success uses the page origin root path |
Argument of type '"github"' is not assignable... | Using strings instead of enums | Use enum values such as OAuthProvider.Github; for Custom OAuth2 use OAuthProvider.CustomOauth2 (2.6.0 built-in) |
| Accessing via IP, still returns to the login page after OAuth | In HTTP + IP scenarios the browser blocks third-party cookies | Switch to localhost or SSH port forwarding; or use a cookie-independent path such as Custom Token / File Token |
After login account.get() 401 | Session expired or environment switched | The frontend should redirect to the login page when account.get() fails; confirm sessions are not reused across SIT/production |
Database and Permissions
| Symptom | Cause | Fix |
|---|---|---|
| All users can see all rows; row-level permissions are not taking effect | Row Security is not enabled on the table, or overly broad permissions were explicitly passed when creating rows | createTable({ rowSecurity: true }) + grant only create("users") at the table level, omit permissions when creating rows; see permissions.md |
Invalid permission format | Hand-built permission strings have syntax errors | Use the SDK's Permission.read(Role.user(id)) helper to construct them; see permissions.md |
Creating a row via the Client SDK with Role.label() returns 401 (Permissions must be one of: (any, users, user:xxx, ...)) | Row-level permissions via the Client SDK can only grant roles the caller owns | Put label-type roles in table-level permissions; at row level use Role.user(自己) / Role.team(已加入团队) instead |
Existing permissions are lost after updateRow | When updateRow is passed permissions, it performs afull replacement | Read the row first to get $permissions, merge, then submit the whole set; see permissions.md |
Index creation error: cannot reference $createdAt | Indexes attributes can only use explicit business columns | First create a business time column (e.g. createdAt) and then the composite index; query sorting can still use $createdAt |
Column stays in processing forever (self-hosted) | The databases worker is not running or the queue is backed up | Check GET /v1/health/queue/databases; check the worker container status and restart; see the "Self-hosted" section below |
Cannot set default value for required ... | Column has both required: true and default set | Choose one: either nullable with a default, or required without a default |
Writing to the database returns database_storage_limit_exceeded (413) | The project's database storage quota is exhausted | Adjust the project quota or clean up data; see the Console admin-plane documentation for the quota model |
Storage
| Symptom | Cause | Fix |
|---|---|---|
<img> Loading preview/view returns 404 although the file exists | Under fileSecurity: true, insufficient permission always returns 404 (hides existence); over cross-origin HTTP, <img> does not carry the session cookie | Do not assign the SDK-returned URL directly to <img src>; fetch a Blob URL via an SDK-authenticated request, or have the server issue a short-lived File Token; see storage.md |
storage.getFilePreview() The returned URL does not open | That method only assembles a URL string and does not go through the SDK's auth layer | Same as above: Blob URL or File Token |
| Deleting files uploaded by others returns 403 | File-level delete permission was granted only to the uploader | For team collaboration use Permission.delete(Role.team(teamId)) |
| Upload returns 413 / 400 | Bucket maximumFileSize exceeded, or the extension is not in allowedFileExtensions | Adjust the bucket configuration or pre-validate on the frontend |
Storage bucket with the requested ID could not be found | The initialization script only created database tables and missed the buckets | Add bucket creation steps to the initialization checklist |
Functions
| Symptom | Cause | Fix |
|---|---|---|
Execution failed: Internal curl error ... Error Number: 6 (DNS resolution failure, common in self-hosting) | The function code used an external URL to initialize the Client, which the sandbox cannot resolve | Prefer the runtime-injected APPWRITE_FUNCTION_API_ENDPOINT; see functions.md |
Synchronous execution (async: false) always times out at 408 | Load balancer 30-second connection timeout + cold start | Switch to async: true + getExecution polling |
| Triggered execution reports a missing scope | createExecution Requires execution.write, not functions.write | Check both scopes on the API Key |
| 2.6.0: passing the Function API Key via query string no longer works | Since 2.6.0, Function API Keys are no longer accepted via query string | Use a protected header (x-appwrite-key) or the platform's runtime-injected authentication path; avoid leaking via URLs, logs, and proxies |
| 2.6.0: Function/Site user install/build commands fail outright | When restricted-identity security conditions are not met, there is no longer a fallback to elevated execution | Fix the commands so they run under the restricted identity; do not attempt to disable the restricted identity |
Platform and Frontend
| Symptom | Cause | Fix |
|---|---|---|
CORS 403 / blocked by CORS policy | The frontend's hostname/IP is not registered as a Platform (or the Project ID is misconfigured) | First verify the projectId, then register all hostnames actually used to access the frontend (including intranet IPs and Sites subdomains); platform management can only use a Console account Session, not a project API Key |
| Only localhost can access it; switching to an IP fails | Only localhost was registered | Register the actual IP; ports are not part of matching |
createPlatform reports User (role: guests) missing scopes | The Console SDK only has createEmailPasswordSession, not setCookie, or a project API Key was used by mistake | Log in to the Console first, then call with setCookie; see overview.md |
Changing .env.local has no effect | A same-named Shell environment variable takes precedence, or dist/ / Vite cached the old value | env Check and clean up; clear dist and node_modules/.vite, then restart |
Realtime channel reports TypeError: xxx is not a function | The channel constant was called as a function | In the Web SDK, construct channels with Channel.tablesdb(db).table(t).row(r) / Channel.files(); see client-sdk/web.md |
Self-Hosting Specifics
| Symptom | Cause | Fix |
|---|---|---|
Attribute/column status stuck at processing | worker-databases is not running or has crashed | GET /v1/health/queue/databases Check the backlog; restart the worker; note that messages from the downtime may already have been consumed — rebuild resources if necessary |
| Sites capability unavailable / restricted by allowlist | _APP_SITES_WHITELIST_EMAILS controls access | Contact operations to configure the allowlist; for API Key scenarios, the project Team must have a member with the owner role on the list |
| Site URL 404 or 301 in the Console preview | The deployment is not ready/not activated, or a protected preview domain was used | Verify the deployment status; use Proxy.createSiteRule to create an trigger=manual public rule |
| Sites pages open but API calls fail | The Sites domain is not registered as a Platform | Register the full Sites hostname as a Web Platform |
| SSR pages return 401/404 and sessions cannot be established | The Sites proxy does not pass through Cookie/Set-Cookie | For authentication, switch to a Client Component + Client SDK; on the server, read the database with an API Key (Site Variable secret: true) |
Debugging Tips
Verify the Session in the browser console:
fetch('<endpoint>/v1/account', { headers: { 'X-Appwrite-Project': '<PROJECT_ID>' }, credentials: 'include' }).Verify a server-side API Key: trial-run a read-only call such as
Users.list()and catchAgentbaseExceptionto inspectcode/type.SDK typed error models: JS throws
AgentbaseException(codeis the HTTP status code,typeis the server error type, with the raw response body attached); Java throws checkedio.agentbase.exceptions.AgentbaseException(getCode()/getType()/getMessage()).For storage-type 404, check permissions before existence (
fileSecuritysemantics); see storage.md.