pubkey/rxdb · error · RxError

UT7

UT7

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

What it means

UT7 is thrown by ensureRxStorageInstanceParamsAreCorrect (src/rx-storage-helper.ts:883) when the schema enables attachment compression (schema.attachments.compression: true) but the storage instance being created does not support compressed attachments. Like UT5/UT6 it is a fail-fast configuration guard so incompatible options never reach the storage layer.

Source

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

/**
 * 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;
    } else {
        return false;
    }
}

export function getChangedDocumentsSinceQuery<RxDocType, CheckpointType>(
    storageInstance: RxStorageInstance<RxDocType, any, any, CheckpointType>,
    limit: number,
    checkpoint?: CheckpointType

View on GitHub (pinned to af6fb65f94)

Solutions

1. Set attachments.compression to false (or remove the attachments options) if you do not need compressed attachments.
2. If you need compression, use the RxDB premium attachment-compression plugin with a storage that supports it, so the flag is valid.
3. Compress attachment data yourself (e.g. gzip in application code) before putting it as an uncompressed attachment if you must stay on a plain storage.
4. For an existing collection with the flag, create a new schema version via migration instead of mutating the live schema.

Example fix

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

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

// detect attachment compression in the schema before creating the instance
const wantsAttachmentCompression =
  mySchema.attachments && mySchema.attachments.compression === true;

if (wantsAttachmentCompression && !attachmentCompressionStorage) {
  console.warn('attachments.compression requires a storage that supports it (premium plugin)');
}

try {
  await myRxDatabase.addCollections({ files: { schema: mySchema } });
} catch (err) {
  if (err && err.code === 'UT7') {
    console.error('attachments.compression enabled but storage does not support it');
    return;
  }
  throw err;
}

When it happens

Trigger: Creating a collection/storage instance with a schema that sets attachments: { compression: true } while the target RxStorage requires plain attachment params (the attachment-compression plugin is missing or the storage cannot handle it).

Common situations: Enabling attachment compression (a premium feature) without using a storage that supports it; copying a schema from a premium setup into a project using a plain storage; enabling the flag 'to save space' while the runtime lacks the required plugin, so instance creation fails immediately.

Related errors

• UT5
• DB14
• DB3
• DB9
• COL20

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