octobercms/october · error · Error

Media Manager image crop popup option "alias" is not set.

Error message

Media Manager image crop popup option "alias" is not set.

What it means

Front-end Error thrown in the imagecroppopup.js widget's init(): the 'alias' option is undefined. The alias is the server-side MediaManager widget alias; the popup JS needs it to address the correct AJAX handler when loading crop data. Without it the widget refuses to initialise, immediately after dispose() has cleared prior DOM references.

Source

Thrown at modules/media/widgets/mediamanager/assets/js/mediamanager.imagecroppopup.js:47

        this.show();
    }

    dispose() {
        this.unregisterHandlers();
        this.removeAttachedControls();

        this.$popupRootElement.remove();
        this.$popupRootElement = null;
        this.$popupElement = null;
        this.selectionSizeLabel = null;
        this.imageArea = null;
        this.hRulerHolder = null;
        this.vRulerHolder = null;
    }

    init() {
        if (this.options.alias === undefined) {
            throw new Error('Media Manager image crop popup option "alias" is not set.');
        }

        this.$popupRootElement = $('<div/>');
        this.registerHandlers();
    }

    show() {
        const data = {
            path: this.path
        };

        this.$popupRootElement.popup({
            extraData: data,
            size: 'adaptive',
            adaptiveHeight: true,
            handler: this.options.alias + '::onLoadImageCropPopup'
        });
    }

View on GitHub (pinned to b608633a7e)

Solutions

1. Pass the MediaManager widget's alias in the options: alias must equal the server widget alias (the same one used in data-control="mediamanager" initialization).
2. If you trigger cropping from custom UI, reuse the stock invocation path (the media manager's own crop command) instead of building the popup by hand.
3. After overriding media manager JS assets, diff against the shipped files to confirm options are forwarded intact.

Example fix

// before
const popup = new $.oc.mediaManager.imageCropPopup({
    path: imagePath
});

// after
const popup = new $.oc.mediaManager.imageCropPopup({
    path: imagePath,
    alias: mediaManagerAlias // e.g. the widget alias rendered by the server
});

if (!options || options.alias === undefined) {
    throw new Error('imageCropPopup requires options.alias (the MediaManager widget alias)');
}
new $.oc.mediaManager.imageCropPopup(options);

function hasCropPopupOptions(o) {
    return !!o && o.alias !== undefined && typeof o.path === 'string';
}

When it happens

Trigger: Instantiating the image crop popup via new $.oc.mediaManager.imageCropPopup({...}) without options.alias, or invoking it from custom JS that builds options dynamically and skips the alias key. The stock MediaManager JS passes the widget's own alias through.

Common situations: Custom 'crop image' buttons or Froala integrations that construct the popup manually; overriding media manager JS assets and dropping the alias from the options object; version upgrades changing which options are forwarded.

Related errors

• Media Manager popup option "alias" is not set.
• A row is not found for the updated data
• Trying to get selected row without a popup reference.
• command option is not set for toolbar button
• command option is not set for menu item

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