Docs
Contents

FAQ

This chapter compiles the most frequently encountered technical issues, the HTTP error code diagnostic matrix, and configuration troubleshooting solutions for enterprises running Agentbase in production. Content is organized into six major topics: architecture and storage modes (JsonTable / Shared V2), authentication and API Key permission scopes, model gateway and DashScope access, knowledge base hybrid retrieval and lexicon binding, memory enablement and distillation evolution, and the agent workbench and AgentOps observability.

Feature Overview

When developers or operators are blocked while working in the Console, or receive non-2xx responses from data-plane APIs via the SDK / REST API, quickly distinguishing “instance deployment-level restrictions (Capability)”, “project-level service switches (Services)”, and “permission and credential scope (RBAC / Scope)” from “upstream model/storage dependency failures” is key to shortening MTTR (mean time to recovery).

This chapter provides a standardized troubleshooting decision path, helping engineering and operations teams investigate common issues; confirm the cause using the environment configuration and error logs.

Troubleshooting topic classificationCore modules and scenarios coveredTypical associated status codes or error identifiers
One: Architecture, versions, and storage modesVersion verification, SDK response format negotiation, JsonTable vs Shared V2 table mode conversion, project independent read-only fence400 (format mismatch), 409 (state conflict), 412 (table mode or deployment unsupported), 503 (drain window)
Two: Authentication, sessions, and API Key permission scopesConsole login MFA/email verification guards, missing API Key Scope, Dev Key restrictions, frontend CORS blocking401 general_unauthorized_scope, 401 user_unauthorized, 403 (CORS / platform not registered)
Three: Model gateway and DashScope accessVendor preset import, API Key masking, model access, and rate limits401 (upstream vendor Key invalid), 429 (RPM/TPM or monthly budget exceeded), 502/504 (upstream timeout)
Four: Knowledge base hybrid retrieval and lexicon bindingDocument parsing failures, Embedding 1024-dimension validation, synonym/stopword lexicon effective timing, GraphRAG/Wiki build interruption400 (dimension mismatch), 412 (advanced index not enabled), document status failed
Five: Memory enablement and distillation evolutionShared V2 prerequisite checks, asynchronous write jobId polling, partial_failed diagnostics, four pipeline types and skill secondary confirmation412 (not Shared V2), LLM_REQUEST_REJECTED, task status partial_failed / failed
Six: Agent workbench and AgentOps operationsWorkbench API Key authentication, sidebar entries and interface visibility, index quality review pending area, restricted identity function errorsSandbox 502/503/504, evaluation status pending_review, empty report panel explanation

Core Concepts and Architecture

Quick Reference Table of High-Frequency HTTP Status Codes and Error Types

HTTP status codeError type or characteristic identifierRoot cause layerStandard remediation action
400general_argument_invalid / response format mismatchProtocol and parameter layerCheck required parameters and field length constraints; if using a custom SDK (e.g. agentbase-node-sdk@2.12.0), make sure X-AppBase-SDK: true and X-Appwrite-Response-Format: 2.12.0 are sent.
401general_unauthorized_scopeAPI Key permission layerGo to project Overview → Integrations → API keys and check the missing scopes for that key (e.g. users.read, databases.write).
401user_unauthorized / CORS errorOrigin and session layerOn the server side, check that X-Appwrite-Key is passed correctly; for browser cross-origin errors, check the web hostname under Overview → Platforms, the actual Origin, and request identity.
403project_database_read_only / project_storage_read_onlyPlatform read-only governance layerThe current project has been placed in database read-only or file storage read-only state by the platform administrator; immediate deletion of a single row/file is still possible, while regular writes require the administrator to lift the read-only state before retrying.
409document_already_exists / state version conflictConcurrency and idempotency layerA duplicate custom $id, or the expected version number (version / expectedDatabase) passed when updating a memory or switching read-only state does not match the latest online state; re-read the latest record first.
412Precondition Failed (prerequisites not met)Deployment capability and prerequisitesFor example, advanced indexing or Memory prerequisites may be missing. Other disabled or unavailable capabilities may return different status codes; inspect the error type.
429general_rate_limit_exceeded / Gateway token limit exceededRate limit and budget layerThe platform request rate limit or the LLM Gateway Key's monthly token budget/RPM threshold has been triggered; a Dev Key can be used in development environments, while production environments need raised quotas or backoff retries.
502 / 503 / 504Execution path or upstream response errorInvestigate the specific requestFunction application responses can also return these codes; use execution details, logs, and environment. If the outcome is unknown, check side effects before retrying.

Roles, Entry Points, and Relationships

Different categories of production issues need to be verified and fixed on the corresponding governance pages in the Console. The table below lists the Console entry points and the required role permissions for each troubleshooting scenario:

Troubleshooting scenarioConsole verification entryExact route pathRole / permission required to fix
Verify account MFA, recovery codes, and pending project deletion recoveryTop navigation Account/console/account (Overview / Sessions / Project cleanup / Table mode conversions)The account owner (project recovery requires organization owner)
Verify frontend cross-origin and API Key scopeProject Overview → Integrations/console/project-{region}-{project}/overview/platforms · .../api-keysplatforms.write / keys.write; owner / admin among default organization roles
Verify project table mode and client service switchesProject Settings → Overview/console/project-{region}-{project}/settingsowner / admin / developer / editor (column deletion only in owner)
Verify missing 30-day usage and quota levelsProject Metering / organization Usage/console/project-{region}-{project}/usage/aggregatesProject entry requires project read access; organization usage depends on deployment and authorization
Verify model provider connectivity and Key budgetProject Models / AI Gateway/console/project-{region}-{project}/llm-gateway · .../ai-gatewayProject members with models and gateway write permission
Verify slow requests, low-scoring replies, and parsing evaluationsProject AgentOps/console/project-{region}-{project}/observability · /logsProject read and relevant observability access; evaluation tasks require write permission

Feature Details and Operation Guide

This section answers frequently asked difficult questions one by one across the six major production topics and provides step-by-step operational guidance.

Topic One: Architecture, version compatibility, and storage modes (JsonTable / Shared V2)

1. How to accurately verify the server version of the current deployment instance? Why do SDK requests report a response format mismatch?

2. How to choose and convert between a project's shared tables (JsonTable), exclusive tables, and the OceanBase Shared V2 table mode?

3. What causes the error project_database_read_only / project_storage_read_only or 503 when writing to the database or uploading files?

Topic Two: Authentication, Sessions, Sidebar Visibility, and API Key Permission Scopes

4. Why can't I see “AI Gateway”, “Messaging”, “Sites”, or “Reports” in the Console's left sidebar?

The reasons these entries are hidden differ; use the following checklist to find your case:

5. After logging in, I keep being bounced back to the login page, or I am forcibly redirected to /console/verify-email or /console/mfa?

Topic Three: Model Gateway, AI Gateway, and DashScope Integration

6. What is the difference between LLM Gateway (models) and AI Gateway (unified AI gateway)? Can their credentials be mixed?

Topic Four: Knowledge Base Hybrid Retrieval, Lexicon Intervention, and Advanced Indexes

7. After binding a synonym lexicon and a stopword lexicon to the knowledge base, do I need to re-upload and re-chunk all documents? What should I do if GraphRAG / Wiki construction gets stuck?

Topic Five: Enabling Long-Term Memory, Asynchronous Writes, and Skill Distillation

8. Why can't I find memories after the Memory write API returns HTTP 202, or why does the task status show partial_failed?

Topic Six: Agent Workspace, Cloud Functions, and AgentOps Observability

9. When a cloud Function execution fails, how do I distinguish a platform sandbox issue from a business code bug? How do I deploy a JAR package directly with Java 17?

10. Why do some records in AgentOps knowledge index quality evaluation have no generated scores, or why is the Reports dashboard's Token waste panel empty?

Versions and Compatibility

How do I confirm the deployment version? Call the public endpoint GET /v1/health/version to read the target instance's version. A service version of 2.10.0 should return {"version":"2.10.0"}; do not substitute the local source code version or results from other environments for what the target instance returns.

SDK requests report a response format mismatch? Clients using Agentbase's in-house SDK should send X-AppBase-SDK: true and set X-Appwrite-Response-Format to match the target instance's service version (for example, use 2.10.0 for a 2.10.0 instance); official Appwrite SDKs use a separate compatibility ceiling (by default at most 1.9.0). In strict mode, mismatched requests are rejected; in lenient mode, they are only flagged in the response header X-Appwrite-Warning. Actual behavior is governed by the deployment environment variables.

FAQ and Troubleshooting

In addition to the six topics above, the following three cross-module operations FAQs supplement the guide:

Q1: What does it mean when a day in the recent 30 UTC-day usage view (Usage Aggregates) shows “Missing” or “Incomplete”?

Cause and troubleshooting steps: The 30 UTC-day aggregate views provided by Agentbase at the account, organization, and project levels strictly distinguish between actual usage of 0 and missing/incomplete metering data. When the underlying metering source is delayed, checkpoints are missing, or subranges are not aligned, the interface explicitly marks “Incomplete” along with the specific reason, and never incorrectly renders missing data as 0. When you see an “Incomplete” notice, refer to the reason shown on the page and wait for the metering level to catch up; never use the understated values from an incomplete state as the basis for final billing reconciliation.

Q2: I batch-deleted inactive projects on the organization's Project cleanup page and now regret it—can they be recovered?

Cause and troubleshooting steps: Recovery is possible, but you must act before the background physical cleanup task officially starts. After the organization Owner submits deletion in Organization → Project cleanup, the project first enters a Pending deletion (pending deletion) buffer state. Immediately go to the top navigation tab Account → Project cleanup, locate the target project in the pending deletion list, confirm its status is still Pending (not yet entered Purging), and click the Restore button on the right to cancel the physical deletion and restore all project resources without loss.

Q3: How do I quickly find all historical execution records of a specific HTTP request path in a cloud Function?

Cause and troubleshooting steps: There is no need to page through the full execution history. Go to the target Function → Executions page and use the Execution Paths feature: first browse the deduplicated, lexicographically sorted list of request paths page by page; in 2.10.0 you can filter by path (exact full-path match or regex match pathMatch=exact|regex) and method (such as POST, GET). After selecting the target path, you can drill down directly to view all historical execution durations, response codes, and logs for that path.