Docs
Contents

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

SymptomCauseFix
Network error / cannot connectendpoint 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 scopesConsole → 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 timeoutNetwork issues or misconfigured environmentVerify the environment; add a timeout in the server-side SDK; if failures persist, check the instance health endpoint

Authentication and OAuth

SymptomCauseFix
This provider is disabled...Provider not enabled for the projectConsole → 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 PlatformConsole → project → Overview → Platforms, add the hostname; see overview.md
OAuth login succeeds but the login page is still shownCallback URL mismatch or the session cookie was not setThe 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 enumsUse 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 OAuthIn HTTP + IP scenarios the browser blocks third-party cookiesSwitch to localhost or SSH port forwarding; or use a cookie-independent path such as Custom Token / File Token
After login account.get() 401Session expired or environment switchedThe frontend should redirect to the login page when account.get() fails; confirm sessions are not reused across SIT/production

Database and Permissions

SymptomCauseFix
All users can see all rows; row-level permissions are not taking effectRow Security is not enabled on the table, or overly broad permissions were explicitly passed when creating rowscreateTable({ rowSecurity: true }) + grant only create("users") at the table level, omit permissions when creating rows; see permissions.md
Invalid permission formatHand-built permission strings have syntax errorsUse 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 ownsPut label-type roles in table-level permissions; at row level use Role.user(自己) / Role.team(已加入团队) instead
Existing permissions are lost after updateRowWhen updateRow is passed permissions, it performs afull replacementRead the row first to get $permissions, merge, then submit the whole set; see permissions.md
Index creation error: cannot reference $createdAtIndexes attributes can only use explicit business columnsFirst 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 upCheck 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 setChoose 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 exhaustedAdjust the project quota or clean up data; see the Console admin-plane documentation for the quota model

Storage

SymptomCauseFix
<img> Loading preview/view returns 404 although the file existsUnder fileSecurity: true, insufficient permission always returns 404 (hides existence); over cross-origin HTTP, <img> does not carry the session cookieDo 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 openThat method only assembles a URL string and does not go through the SDK's auth layerSame as above: Blob URL or File Token
Deleting files uploaded by others returns 403File-level delete permission was granted only to the uploaderFor team collaboration use Permission.delete(Role.team(teamId))
Upload returns 413 / 400Bucket maximumFileSize exceeded, or the extension is not in allowedFileExtensionsAdjust the bucket configuration or pre-validate on the frontend
Storage bucket with the requested ID could not be foundThe initialization script only created database tables and missed the bucketsAdd bucket creation steps to the initialization checklist

Functions

SymptomCauseFix
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 resolvePrefer the runtime-injected APPWRITE_FUNCTION_API_ENDPOINT; see functions.md
Synchronous execution (async: false) always times out at 408Load balancer 30-second connection timeout + cold startSwitch to async: true + getExecution polling
Triggered execution reports a missing scopecreateExecution Requires execution.write, not functions.writeCheck both scopes on the API Key
2.6.0: passing the Function API Key via query string no longer worksSince 2.6.0, Function API Keys are no longer accepted via query stringUse 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 outrightWhen restricted-identity security conditions are not met, there is no longer a fallback to elevated executionFix the commands so they run under the restricted identity; do not attempt to disable the restricted identity

Platform and Frontend

SymptomCauseFix
CORS 403 / blocked by CORS policyThe 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 failsOnly localhost was registeredRegister the actual IP; ports are not part of matching
createPlatform reports User (role: guests) missing scopesThe Console SDK only has createEmailPasswordSession, not setCookie, or a project API Key was used by mistakeLog in to the Console first, then call with setCookie; see overview.md
Changing .env.local has no effectA same-named Shell environment variable takes precedence, or dist/ / Vite cached the old valueenv Check and clean up; clear dist and node_modules/.vite, then restart
Realtime channel reports TypeError: xxx is not a functionThe channel constant was called as a functionIn the Web SDK, construct channels with Channel.tablesdb(db).table(t).row(r) / Channel.files(); see client-sdk/web.md

Self-Hosting Specifics

SymptomCauseFix
Attribute/column status stuck at processingworker-databases is not running or has crashedGET /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 accessContact 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 previewThe deployment is not ready/not activated, or a protected preview domain was usedVerify the deployment status; use Proxy.createSiteRule to create an trigger=manual public rule
Sites pages open but API calls failThe Sites domain is not registered as a PlatformRegister the full Sites hostname as a Web Platform
SSR pages return 401/404 and sessions cannot be establishedThe Sites proxy does not pass through Cookie/Set-CookieFor authentication, switch to a Client Component + Client SDK; on the server, read the database with an API Key (Site Variable secret: true)

Debugging Tips