octobercms/october · error · Error

Inspector unique key is a required string

Error message

Inspector unique key is a required string

What it means

The `uniqueId` argument of showModal() must be a non-empty string; the inspector uses it to key its Vue application, event channels, and change tracking, so a missing or numeric id breaks identity. Passing a numeric database id is the classic trigger — JavaScript numbers are not strings, and the check is strict.

Source

Thrown at modules/backend/vuecomponents/inspector/assets/js/classes/host.js:20

    showModal(title, obj, dataSchema, uniqueId, options, parentObj) {
        if (typeof title !== 'string' || !title.length) {
            throw new Error('Inspector title is a required string');
        }

        if (typeof obj !== 'object') {
            throw new Error('Inspector Object must be an object');
        }

        if (parentObj !== undefined && typeof parentObj !== 'object') {
            throw new Error('Inspector Parent Object must be an object');
        }

        if (!Array.isArray(dataSchema)) {
            throw new Error('Inspector data schema must be an array');
        }

        if (typeof uniqueId !== 'string' || !uniqueId.length) {
            throw new Error('Inspector unique key is a required string');
        }

        if (options) {
            if (typeof options !== 'object') {
                throw new Error('options must be an object');
            }

            if (options.buttonText && typeof options.buttonText !== 'string') {
                throw new Error('options.buttonText must be a string');
            }

            if (options.size && typeof options.size !== 'string') {
                throw new Error('options.size must be a string');
            }

            if (options.description && typeof options.description !== 'string') {
                throw new Error('options.description must be a string');
            }

View on GitHub (pinned to b608633a7e)

Solutions

1. Coerce ids: showModal(title, obj, schema, String(record.id)).
2. Generate a key once per modal instance (e.g. 'inspector-' + Date.now()) and pass it consistently.
3. Recheck argument order: (title, obj, dataSchema, uniqueId, options, parentObj).

Example fix

// before
host.showModal(title, obj, schema, record.id);

// after
host.showModal(title, obj, schema, String(record.id));

const uniqueId = typeof rawId === 'string' && rawId.length ? rawId : String(rawId);
host.showModal(title, obj, schema, uniqueId);

function isInspectorUniqueId(value) {
    return typeof value === 'string' && value.length > 0;
}

When it happens

Trigger: showModal(title, obj, schema, model.id) where id is a number; omitting uniqueId so the `options` value shifts into its position; passing '' from a not-yet-generated key.

Common situations: Using record primary keys as inspector ids without String(); generating ids per modal open and racing initialization; positional-argument mistakes after the signature gained `options`.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• Inspector title is a required string
• Inspector Object must be an object
• Inspector Parent Object must be an object
• Inspector data schema must be an array
• getDynamicOptionsExtraData must return an object

AI-assisted analysis of octobercms/october@b608633a7e (2026-08-21). Data as JSON: /api/errors/3bab144821a0f728. Report an issue: GitHub.