appwrite/appwrite · error · Appwrite\Extend\Exception

GENERAL_QUERY_INVALID

GENERAL_QUERY_INVALID

Error message

The query's syntax is invalid. Please check the query and try again.

What it means

GENERAL_QUERY_INVALID signals the database rejected a query issued during a transaction update because its syntax was invalid. The Transactions Update action catches the adapter's QueryException while applying transaction operations and rewraps it as this error, preserving the underlying message. It means the request reached the server but the query payload (queries param or internal query built from the transaction) was malformed.

Solutions

  1. Validate queries with the SDK's Query helper methods instead of raw strings before sending
  2. Print and inspect the raw queries payload; check for JSON/encoding corruption
  3. Verify the Appwrite SDK and server versions are aligned (query operator support differs across versions)
  4. Check the error's underlying message for the exact parser complaint and fix that token

Example fix

// before
const queries = ['equal(name, "a")']; // hand-written, wrong quoting
// after
const queries = [Query.equal('name', ['a'])]; // SDK-generated, valid syntax
Defensive patterns

Strategy: validation

Validate before calling

function validateQueries(queries) {
  if (!Array.isArray(queries)) throw new Error('queries must be an array');
  for (const q of queries) {
    if (typeof q !== 'string') throw new Error('each query must be a serialized Query string');
    if (!q.includes('(') || !q.endsWith(')')) throw new Error(`malformed query: ${q}`);
  }
}

Type guard

const isQueryArray = (v) => Array.isArray(v) && v.every((q) => typeof q === 'string');

Try / catch

try {
  await db.updateTransaction({ transactionId, queries });
} catch (e) {
  if (e.code === 400 && e.type === 'general_query_invalid') {
    console.error('Invalid query syntax:', e.message);
  }
  throw e;
}

Prevention

When it happens

Trigger: PATCH /v1/databases/transactions/:transactionId where the supplied queries array contains a malformed Appwrite query string (bad method name, unbalanced parentheses, invalid JSON values, unsupported operator), or the transaction body contains operations that deserialize into invalid Query objects.

Common situations: Hand-building query strings without the SDK's Query helper; passing SDK Query objects through json_encode incorrectly; copying query examples across Appwrite versions where operators changed; URL-encoding issues stripping characters from the queries parameter.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors


AI-assisted analysis of appwrite/appwrite@ca3c55abfe (2026-09-16). Data as JSON: /api/errors/8d26f9fabf186a70. Report an issue: GitHub.

Appendix: source

Thrown at src/Appwrite/Platform/Modules/Databases/Http/Databases/Transactions/Update.php:348

                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw new Exception(Exception::DOCUMENT_INVALID_STRUCTURE, $e->getMessage());
            } catch (LimitException $e) {
                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw new Exception(Exception::ATTRIBUTE_LIMIT_EXCEEDED, $e->getMessage());
            } catch (TransactionException $e) {
                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw new Exception(Exception::TRANSACTION_FAILED, $e->getMessage());
            } catch (QueryException $e) {
                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw new Exception(Exception::GENERAL_QUERY_INVALID, $e->getMessage());
            } catch (AuthorizationException $e) {
                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw new Exception(Exception::USER_UNAUTHORIZED, previous: $e);
            } catch (\Throwable $e) {
                $authorization->skip(fn () => $dbForProject->updateDocument('transactions', $transactionId, new Document([
                    'status' => 'failed',
                ])));
                throw $e;
            }

            foreach ($databaseOperations as $databaseInternalId => $count) {
                $database = $authorization->skip(fn () => $dbForProject->skipFilters(
                    fn () => $dbForProject->findOne('databases', [
                        Query::equal('$sequence', [$databaseInternalId])
                    ]),
                    APP_DATABASES_SUBQUERIES

View on GitHub (pinned to ca3c55abfe)