appsmithorg/appsmith · error · Error

onUiChange expects a function as parameter

Error message

onUiChange expects a function as parameter

What it means

Plain Error thrown by the custom-widget runtime's appsmith.onUiChange(fn) when the argument is not a function. onUiChange registers a subscriber invoked immediately with the current ui model and whenever the UI changes from outside the widget. A non-function argument would be un-callable, so registration is rejected and no subscriber is added.

Source

Thrown at app/client/src/widgets/CustomWidget/component/customWidgetscript.js:225

          if (typeof fn !== "function") {
            throw new Error("onThemeChange expects a function as parameter");
          }

          themeSubscribers.push(fn);
          fn(window.appsmith.theme);

          return () => {
            // Unsubscribe from theme changes
            const index = themeSubscribers.indexOf(fn);

            if (index > -1) {
              themeSubscribers.splice(index, 1);
            }
          };
        },
        onUiChange: (fn) => {
          if (typeof fn !== "function") {
            throw new Error("onUiChange expects a function as parameter");
          }

          uiSubscribers.push(fn);
          fn(window.appsmith.ui);

          return () => {
            // Unsubscribe from UI changes
            const index = uiSubscribers.indexOf(fn);

            if (index > -1) {
              uiSubscribers.splice(index, 1);
            }
          };
        },
        onModelChange: (fn) => {
          if (typeof fn !== "function") {
            throw new Error("onModelChange expects a function as parameter");
          }

View on GitHub (pinned to 8cd9021c24)

Solutions

1. Pass a function reference: appsmith.onUiChange((ui) => { ... }).
2. Store the returned unsubscribe function and call it in your widget cleanup.
3. Guard with typeof fn === 'function' if you conditionally subscribe.

Example fix

// before
appsmith.onUiChange(uiModel);
// after
appsmith.onUiChange((ui) => render(ui));

if (typeof handler !== 'function') {
  console.warn('onUiChange: expected a function');
  return;
}
const unsubscribe = appsmith.onUiChange(handler);

function isListener(v: unknown): v is Function {
  return typeof v === 'function';
}

When it happens

Trigger: Calling appsmith.onUiChange() with no argument, a string, a number, an object, or undefined; passing the result of a function call instead of the function reference.

Common situations: Boilerplate left half-edited; passing a model object instead of a listener; refactoring broke the handler reference.

Related errors

• onThemeChange expects a function as parameter
• The ${path} path must start with 'https://'.
• error
• Please enter a target origin URL.
• resetWidget expected STRING for 'widgetName' argument but re

AI-assisted analysis of appsmithorg/appsmith@8cd9021c24 (2026-08-12). Data as JSON: /api/errors/179db3f0fd0c3cc2. Report an issue: GitHub.