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

  1. Re-fetch from the first page without a cursor and paginate again.
  2. Verify the anchor exists first: GET /v1/databases/{dbId}/collections/{cursorId} should return 200.
  3. 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

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


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)