pubkey/rxdb · error · RxError

DOC18

DOC18

Error message

        RxDB Error-Code: ${message}.
        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
        
Find out more about this error here: https://rxdb.info/errors.html?console=errors#DOC18 
Still stuck? Ask in the RxDB Discord: https://rxdb.info/chat 

What it means

DOC18 is thrown by getComposedPrimaryKeyOfDocumentData() when one of the fields that make up the composite primary key is undefined in the document data. RxDB cannot compute the document id because a required key component is missing. It is raised whenever any code needs to derive the primary key: checkpoints, internal documents, meta rows, insert helpers.

Source

Thrown at src/rx-schema-helper.ts:159

    return ensureNotFalsy(schemaPart.maxLength);
}

/**
 * Returns the composed primaryKey of a document by its data.
 */
export function getComposedPrimaryKeyOfDocumentData<RxDocType>(
    jsonSchema: RxJsonSchema<RxDocType> | RxJsonSchema<RxDocumentData<RxDocType>>,
    documentData: Partial<RxDocType>
): string {
    if (typeof jsonSchema.primaryKey === 'string') {
        return (documentData as any)[jsonSchema.primaryKey];
    }

    const compositePrimary: CompositePrimaryKey<RxDocType> = jsonSchema.primaryKey as any;
    return compositePrimary.fields.map(field => {
        const value = getProperty(documentData as any, field as string);
        if (typeof value === 'undefined') {
            throw newRxError('DOC18', { args: { field, documentData } });
        }
        return value;
    }).join(compositePrimary.separator);
}


/**
 * Normalize the RxJsonSchema.
 * We need this to ensure everything is set up properly
 * and we have the same hash on schemas that represent the same value but
 * have different json.
 *
 * - Orders the schemas attributes by alphabetical order
 * - Adds the primaryKey to all indexes that do not contain the primaryKey
 * - We need this for deterministic sort order on all queries, which is required for event-reduce to work.
 *
 * @return RxJsonSchema - ordered and filled
 */

View on GitHub (pinned to af6fb65f94)

Solutions

1. Ensure every field listed in schema.primaryKey.fields is present in the document before insert/upsert.
2. Use the dev-mode plugin to see the exact missing field and documentData in the error args.
3. Check for typos in field names and that nested fields (dot-separated in primaryKey.fields) actually exist on the object.
4. If documents come from an old version, run a migration strategy that fills the new key field before writes.

Example fix

// before
await collection.insert({ firstName: 'bar' }); // lastName missing
// after
await collection.insert({ firstName: 'bar', lastName: 'baz' });

import { getPrimaryKeyOfInternalDocument } from 'rxdb/plugins/rx-schema-helper';
function hasAllKeyFields(schema: RxJsonSchema<any>, data: Record<string, any>): boolean {
  const { fields } = schema.primaryKey as any;
  return fields.every((f: string) => getProperty(data, f) !== undefined);
}

function isInsertable<T>(schema: RxJsonSchema<T>, data: Partial<T>): data is T {
  const composite = schema.primaryKey as CompositePrimaryKey<T>;
  return composite.fields.every(field => getProperty(data as any, field as string) !== undefined);
}

try {
  await collection.insert(data);
} catch (err: any) {
  if (err.code === 'DOC18') {
    const missing = err.parameters?.args?.field;
    throw new Error(`Primary key field '${missing}' missing on document`);
  } else throw err;
}

When it happens

Trigger: Inserting/upserting a document where a primaryKey.fields entry is undefined or absent, e.g. schema primaryKey fields ['firstName','lastName'] and insert({firstName:'bar'}) without lastName. Also triggered indirectly via useId, checkpoint writes, replication meta rows (getMetaWriteRow) or getPrimaryKeyOfInternalDocument when the input data lacks a key field.

Common situations: Partial updates or patch objects passed where full document data is expected; documents from an older schema version missing a newly added key field; replication upstream data that does not contain all key fields; typos in field names (JS silently yields undefined).

Related errors

• DOC19
• SC39
• VD2
• DOC2
• DOC3

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