pubkey/rxdb · error · RxError

QU10

QU10

Error message

RxDB Error-Code: QU10. Hint: Error messages are not included in RxDB core to reduce build size. To show the full error messages and to ensure that you do not make any mistakes when using RxDB, use the dev-mode plugin when you are in development mode: https://rxdb.info/dev-mode.html?console=error

What it means

QU10 is thrown by RxQuerySingleResult.getValue when a findOne() query returns no document but throwIfMissing is set, i.e. when .exec(true) (or the throwIfMissing variant) is called and no document matches the query. Instead of returning null, RxDB throws so callers can rely on a non-null RxDocument.

Source

Thrown at src/rx-query-single-result.ts:101

            const doc = documents[i];
            map.set(doc.primary, doc);
        }
        return overwriteGetterForCaching(
            this,
            'docsMap',
            map
        );
    }

    getValue(throwIfMissing?: boolean) {
        const op = this.query.op;
        if (op === 'count') {
            return this.count;
        } else if (op === 'findOne') {
            // findOne()-queries emit RxDocument or null
            const doc = this.documents.length === 0 ? null : this.documents[0];
            if (!doc && throwIfMissing) {
                throw newRxError('QU10', {
                    collection: this.query.collection.name,
                    query: this.query.mangoQuery,
                    op
                });
            } else {
                return doc;
            }
        } else if (op === 'findByIds') {
            return this.docsMap;
        } else {
            // find()-queries emit RxDocument[]
            // Flat copy the array so it won't matter if the user modifies it.
            return this.documents.slice(0);
        }
    }
}

View on GitHub (pinned to af6fb65f94)

Solutions

Use await query.exec() without the true flag if null is an acceptable outcome, then handle the null case.
Verify the selector matches an existing document (check primary key value, _deleted state, and that replication has caught up).
Wrap exec(true) in try/catch when existence is genuinely uncertain and handle the missing-document branch.
For counting-based logic, use count() first or check the collection before demanding a single doc.

Example fix

// before
const doc = await collection.findOne('user-42').exec(true); // throws when absent

// after
const doc = await collection.findOne('user-42').exec();
if (!doc) {
  console.log('user-42 not found');
  return;
}

Defensive patterns

Strategy: try-catch

Validate before calling

const existing = await collection.findOne(id).exec();
if (!existing) {
  throw new Error(`document ${id} does not exist`);
}

Type guard

function isRxDocument<T>(v: T | null): v is T {
  return v !== null && v !== undefined;
}

Try / catch

try {
  const doc = await query.exec(true);
  // doc is guaranteed non-null here
} catch (err) {
  if (err?.code === 'QU10') {
    // handle missing document: create it, return default, or inform the user
    return null;
  }
  throw err;
}

Prevention

Use exec(true) only when absence is a genuine error condition; otherwise use exec() and check for null.
Verify primary-key lookups against replicated state and deleted documents.
Search for exec(true) call sites in code paths that run right after deletes or before replication finishes.

When it happens

Trigger: Calling query.exec(true) on a findOne() query where zero documents match the selector; calling getValue() with throwIfMissing=true on a single-result whose documents array is empty.

Common situations: Assuming a document exists by primary key (lookup after a delete or before a replication has synced it); race between checking existence and reading; tenant-scoped queries where the selector accidentally matches nothing.

Related errors

AI-assisted analysis of pubkey/rxdb@af6fb65f94 (2026-08-31). Data as JSON: /api/errors/71a033ccd8a491ee. Report an issue: GitHub.