pubkey/rxdb · error · RxError

DOC7

DOC7

Error message

RxDB Error-Code: DOC7. 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

DOC7 is thrown by RxDocument.populate() when the schema field has a ref, but no collection with that name exists in the database (this.collection.database.collections[ref] is undefined). The ref points to a collection that was never added via addCollections, or was added under a different name. RxDB cannot resolve the reference without the target collection.

Source

Thrown at src/rx-document.ts:223

            throw newRxError('DOC5', {
                path
            });
        }
        const ref = schemaObj.ref
            ? schemaObj.ref
            : (schemaObj.type === 'array' && schemaObj.items && (schemaObj.items as any).ref
                ? (schemaObj.items as any).ref
                : undefined);
        if (!ref) {
            throw newRxError('DOC6', {
                path,
                schemaObj
            });
        }

        const refCollection: RxCollection = this.collection.database.collections[ref];
        if (!refCollection) {
            throw newRxError('DOC7', {
                ref,
                path,
                schemaObj
            });
        }

        const value = this.get(path);
        if (!value) {
            return PROMISE_RESOLVE_NULL;
        }

        if (schemaObj.type === 'array') {
            return refCollection.findByIds(value).exec().then(res => {
                // Preserve the original array order of the ref ids
                // instead of using the Map iteration order which depends
                // on the query cache and storage return order.
                const result = [];
                for (let i = 0; i < value.length; i++) {

View on GitHub (pinned to af6fb65f94)

Solutions

1. Add the referenced collection to the database via addCollections with the exact name used in ref
2. Align the schema ref string with the actual collection name (names are case-sensitive)
3. Ensure the collection is created before any populate() call runs

Example fix

// before
// schema: { ref: 'heroes' } but db only has 'hero'
await doc.populate('bestFriend'); // DOC7
// after
await myDatabase.addCollections({ heroes: { schema: heroSchema } });

function refCollectionExists(doc: RxDocument, path: string): boolean {
  const schemaObj = getSchemaByObjectPath(doc.collection.schema.jsonSchema, path) as any;
  const ref = schemaObj?.ref ?? schemaObj?.items?.ref;
  return !!ref && !!doc.collection.database.collections[ref];
}
if (!refCollectionExists(doc, 'bestFriend')) throw new Error('missing ref collection');

function collectionExists(db: RxDatabase, name: string): boolean {
  return Object.prototype.hasOwnProperty.call(db.collections, name);
}

try {
  return await doc.populate(path);
} catch (err) {
  if ((err as any).code === 'DOC7') {
    await db.addCollections({ [expectedRef]: { schema } }); // repair and retry once
    return await doc.populate(path);
  }
  throw err;
}

When it happens

Trigger: await doc.populate('bestFriend') where the schema says ref: 'heroes' but the database has no collection named 'heroes'; collection added as 'hero' (typo/singular vs plural); ref collection only created conditionally at runtime; ref copied from another database setup.

Common situations: addCollections call missing the referenced collection; case-sensitive name mismatch between schema ref and collection name; multi-database setups where the ref exists in one database instance but not the one in use.

Related errors

• DOC6
• DOC5

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