appwrite/appwrite · error · Appwrite\Extend\Exception
general_cursor_not_found
general_cursor_not_found
Error message
Collection '{$collectionIdId}' for the 'cursor' value not found. What it means
The cursor value sent to GET /v1/databases/{databaseId}/collections names a collection that does not exist in this database. After the Cursor validator passes, the endpoint loads the cursor document from the per-database metadata collection (database_{internalId}); an empty result means pagination cannot continue from that anchor, so GENERAL_CURSOR_NOT_FOUND is raised with the offending ID.
Solutions
- Re-fetch from the first page without a cursor and paginate again.
- Verify the anchor exists first: GET /v1/databases/{dbId}/collections/{cursorId} should return 200.
- If deletions are frequent, derive each cursor from the immediately preceding response instead of stored state.
Example fix
// before
const next = await databases.listCollections(dbId, [Query.cursorAfter(savedCursorId)]);
// after
try {
const next = await databases.listCollections(dbId, [Query.cursorAfter(savedCursorId)]);
} catch (e) {
if (e.code === 'general_cursor_not_found') {
return databases.listCollections(dbId, [Query.limit(limit)]); // anchor deleted -> restart
}
throw e;
} Defensive patterns
Strategy: try-catch
Validate before calling
async function cursorExists(databases, dbId, cursorId) {
try {
await databases.getCollection(dbId, cursorId);
return true;
} catch {
return false;
}
// if (!await cursorExists(...)) restart from the first page Try / catch
try {
return await databases.listCollections(dbId, [Query.cursorAfter(cursorId)]);
} catch (e) {
if (e.code === 'general_cursor_not_found') {
return databases.listCollections(dbId, [Query.limit(limit)]); // anchor gone: restart at page 1
}
throw e;
} Prevention
- Use cursors taken from the immediately preceding page response
- Restart pagination from the first page when deletions are possible
- Never persist cursors across sessions or environments
When it happens
Trigger: Query.cursor('collectionId') where the ID was deleted, belongs to another database, or is a typo; paginating while another client deletes collections between page requests; reusing a cursor saved from a different environment (dev vs prod).
Common situations: Persisting cursors long-term and replaying them after deletions; concurrent admin operations pruning collections during a paginated export; copy-pasting cursor IDs between projects.
Related errors
- general_cursor_not_found
- general_cursor_not_found
- general_cursor_not_found
- collection_not_found
- collection_not_found
AI-assisted analysis of appwrite/appwrite@a1d520eea4 (2026-08-18).
Data as JSON: /api/errors/cbefbb9e00adee7f.
Report an issue: GitHub.
Appendix: source
Thrown at src/Appwrite/Platform/Modules/Databases/Http/Databases/Collections/XList.php:106
if (!empty($search)) {
$queries[] = Query::search('search', $search);
}
$cursor = Query::getCursorQueries($queries, false);
$cursor = \reset($cursor);
if ($cursor !== false) {
$validator = new Cursor();
if (!$validator->isValid($cursor)) {
throw new Exception(Exception::GENERAL_QUERY_INVALID, $validator->getDescription());
}
$collectionIdId = $cursor->getValue();
$cursorDocument = $dbForProject->getDocument('database_' . $database->getSequence(), $collectionIdId);
if ($cursorDocument->isEmpty()) {
throw new Exception(Exception::GENERAL_CURSOR_NOT_FOUND, ucfirst($this->getContext()) . " '$collectionIdId' for the 'cursor' value not found.");
}
$cursor->setValue($cursorDocument);
}
try {
$collections = $dbForProject->find('database_' . $database->getSequence(), $queries);
$total = $includeTotal ? $dbForProject->count('database_' . $database->getSequence(), $queries, APP_LIMIT_COUNT) : 0;
} catch (OrderException) {
throw new Exception(Exception::DATABASE_QUERY_ORDER_NULL);
} catch (QueryException) {
throw new Exception(Exception::GENERAL_QUERY_INVALID);
}
foreach ($collections as $collection) {
$this->addRowBytesInfo($collection, $dbForProject);
}
View on GitHub (pinned to a1d520eea4)