pubkey/rxdb · error · RxError

UT5

UT5

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

What it means

UT5 (UT = 'ensureRxStorageInstanceParamsAreCorrect' utility checks) is thrown when a collection is created with keyCompression enabled in its schema but the target RxStorage implementation does not support the key-compression plugin's storage requirements. ensureRxStorageInstanceParamsAreCorrect (src/rx-storage-helper.ts:874) guards storage instance creation so misconfiguration fails fast instead of producing corrupt or unusable data in storages that only work with plain (non-compressed) keys.

Source

Thrown at src/rx-storage-helper.ts:874

        changeStream() {
            return storageInstance.changeStream();
        }
    };

    database.storageInstances.add(ret);
    return ret;
}

/**
 * Each RxStorage implementation should
 * run this method at the first step of createStorageInstance()
 * to ensure that the configuration is correct.
 */
export function ensureRxStorageInstanceParamsAreCorrect(
    params: RxStorageInstanceCreationParams<any, any>
) {
    if (params.schema.keyCompression) {
        throw newRxError('UT5', { args: { params } });
    }
    if (hasEncryption(params.schema)) {
        throw newRxError('UT6', { args: { params } });
    }
    if (
        params.schema.attachments &&
        params.schema.attachments.compression
    ) {
        throw newRxError('UT7', { args: { params } });
    }
}

export function hasEncryption(jsonSchema: RxJsonSchema<any>): boolean {
    if (
        (!!jsonSchema.encrypted && jsonSchema.encrypted.length > 0) ||
        (jsonSchema.attachments && jsonSchema.attachments.encrypted)
    ) {
        return true;

View on GitHub (pinned to af6fb65f94)

Solutions

1. Set keyCompression: false in the schema (or remove the flag) if you do not actively need key compression.
2. Install and register the key-compression plugin if you want keyCompression: true, and use a storage that supports it.
3. If compression matters, pick a storage that handles it natively or use a storage with built-in compression instead of schema-level keyCompression.
4. Remember schemas are immutable per collection: for an existing collection, create a new collection/version with a migration instead of editing the live schema.

Example fix

// before
const mySchema = {
  title: 'hero',
  version: 0,
  keyCompression: true,
  primaryKey: 'id',
  properties: { id: { type: 'string', maxLength: 100 } },
  required: ['id']
};

// after
const mySchema = {
  title: 'hero',
  version: 0,
  keyCompression: false,
  primaryKey: 'id',
  properties: { id: { type: 'string', maxLength: 100 } },
  required: ['id']
};

// check before creating the collection
if (mySchema.keyCompression === true) {
  // either remove the flag or ensure the key-compression plugin is registered
  console.warn('keyCompression is enabled; ensure the compression plugin is added');
}

try {
  await myRxDatabase.addCollections({ heroes: { schema: mySchema } });
} catch (err) {
  if (err && err.code === 'UT5') {
    console.error('keyCompression enabled but storage does not support it:', err.parameters.args.params.schema.title);
    // recreate with keyCompression: false or install the plugin
    return;
  }
  throw err;
}

When it happens

Trigger: Calling createRxCollection()/addCollections() with a schema where keyCompression: true while using an RxStorage that rejects compressed params (this check runs for storages that require plain params, e.g. when key compression plugin is not installed or the storage does not handle compression).

Common situations: Copying a schema from a project that used key compression into a new project without the compression plugin; enabling keyCompression to save disk space while switching to a storage (e.g. certain remote or premium storages) that does not support it; upgrading RxDB and moving collection creation to a storage path that now runs the params guard.

Related errors

• SC39
• UT6
• UT7
• DB14
• DB3

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