pubkey/rxdb · error · RxError

DOC19

DOC19

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#DOC19 
Still stuck? Ask in the RxDB Discord: https://rxdb.info/chat 

What it means

DOC19 is thrown by fillPrimaryKey() when the document data already contains a value for the primary key field, but that value differs from the primary key RxDB computed from the composed/composite primary key fields. RxDB derives the primary key deterministically from the schema's primaryKey definition, so a pre-set primary that disagrees with the derived one would break document identity. The library throws to prevent silently creating a document whose id does not match its key fields.

Source

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

    primaryPath: keyof T,
    jsonSchema: RxJsonSchema<T>,
    documentData: RxDocumentData<T>
): RxDocumentData<T> {
    // optimization shortcut.
    if (typeof jsonSchema.primaryKey === 'string') {
        return documentData;
    }

    const newPrimary = getComposedPrimaryKeyOfDocumentData<T>(
        jsonSchema,
        documentData
    );
    const existingPrimary: string | undefined = documentData[primaryPath] as any;
    if (
        existingPrimary &&
        existingPrimary !== newPrimary
    ) {
        throw newRxError(
            'DOC19',
            {
                args: {
                    documentData,
                    existingPrimary,
                    newPrimary,
                },
                schema: jsonSchema
            });
    }

    (documentData as any)[primaryPath] = newPrimary;
    return documentData;
}

export function getPrimaryFieldOfPrimaryKey<RxDocType>(
    primaryKey: PrimaryKey<RxDocType>
): StringKeys<RxDocType> {

View on GitHub (pinned to af6fb65f94)

Solutions

1. Do not set the primary key field yourself; omit it and let RxDB compose it from the key fields.
2. If you must set it, make sure it exactly equals the composed value (fields joined by the schema's separator), e.g. use getComposedPrimaryKeyOfDocumentData() to compute it.
3. Check your schema's primaryKey definition (fields and separator) matches what your code assumes.
4. Enable the dev-mode plugin during development to see the full error message with the offending documentData, existingPrimary and newPrimary values.

Example fix

// before
collection.insert({ id: 'foo', firstName: 'bar', lastName: 'baz' });
// after
// omit the primary, RxDB composes it (with separator '|')
collection.insert({ firstName: 'bar', lastName: 'baz' });
// or compute it correctly:
const id = getComposedPrimaryKeyOfDocumentData(schema, { firstName: 'bar', lastName: 'baz' });
collection.insert({ id, firstName: 'bar', lastName: 'baz' });

import { getComposedPrimaryKeyOfDocumentData } from 'rxdb/plugins/rx-schema-helper';
function validatePrimaryKey(schema: RxJsonSchema<any>, data: Record<string, any>): boolean {
  const primaryPath = schema.primaryKey as string;
  if (data[primaryPath] === undefined) return true; // RxDB will fill it
  const composed = getComposedPrimaryKeyOfDocumentData(schema, data);
  return data[primaryPath] === composed;
}

function hasConsistentPrimaryKey<T>(schema: RxJsonSchema<T>, data: T): data is T & { [k: string]: string } {
  const primaryPath = getPrimaryFieldOfPrimaryKey(schema.primaryKey) as keyof T;
  const existing = (data as any)[primaryPath];
  return existing === undefined || existing === getComposedPrimaryKeyOfDocumentData(schema, data);
}

try {
  await collection.insert(data);
} catch (err: any) {
  if (err.code === 'DOC19') {
    // recompute or strip the primary and retry
    delete data[getPrimaryFieldOfPrimaryKey(collection.schema.primaryKey)];
    await collection.insert(data);
  } else throw err;
}

When it happens

Trigger: Calling collection.insert() (via fillObjectDataBeforeInsert) or collection.bulkInsert() with document data where data[primaryPath] is already set to a string that does not equal the value computed by joining the composite key fields with the separator, e.g. inserting {id: 'foo', firstName: 'bar', lastName: 'baz'} when the composed key yields 'bar|baz'.

Common situations: Migrating code from a schema with a plain primary key to a composite primary key while still setting the old id manually; copying documents between collections with different key definitions; manually crafting documents for seed/fixup scripts; deserializing stored data where the key fields were edited but the primary was not recomputed.

Related errors

• DOC18
• SC39
• VD2
• DOC2
• DOC3

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