ionic-team/ionic-framework · error · Error

framework delegate is missing

Error message

framework delegate is missing

What it means

Thrown by the overlay delegate's attachViewToDom() in overlays.ts when the overlay has a controller (hasController is true) and a component was provided, but no framework delegate is configured. This is the overlay-specific variant of error 8: Ionic needs a framework delegate to instantiate a component-reference, and none is available, so it refuses rather than silently doing nothing.

Source

Thrown at core/src/utils/overlays.ts:942

    inline = parentEl !== null && !hasController;
    workingDelegate = inline ? delegate || coreDelegate : delegate;

    return { inline, delegate: workingDelegate };
  };

  /**
   * Attaches a component in the DOM. Teleports the component
   * to the root of the app.
   * @param component The component to optionally construct and append to the element.
   */
  const attachViewToDom = async (component?: any) => {
    const { delegate } = getDelegate(true);
    if (delegate) {
      return await delegate.attachViewToDom(ref.el, component);
    }
    const { hasController } = ref;
    if (hasController && component !== undefined) {
      throw new Error('framework delegate is missing');
    }
    return null;
  };

  /**
   * Moves a component back to its original location in the DOM.
   */
  const removeViewFromDom = () => {
    const { delegate } = getDelegate();
    if (delegate && ref.el !== undefined) {
      delegate.removeViewFromDom(ref.el.parentElement, ref.el);
    }
  };

  return {
    attachViewToDom,
    removeViewFromDom,
  };

View on GitHub (pinned to 625f9c38ad)

Solutions

1. Install and bootstrap the correct framework integration so its delegate is registered (IonicModule.forRoot / IonicReactRouter/IonReactDelegate / createApp + IonicVue).
2. In tests, either mock the delegate or use inline overlays (component as children) instead of the controller + class reference pattern.
3. If you genuinely have no framework, pass component as a tag string or HTMLElement, or omit it and use slot/inline content.
4. Confirm the overlay is created through the framework-aware controller, not a bare @ionic/core controller, when running inside a framework.

Example fix

// before (no framework delegate registered)
const modal = await modalController.create({ component: MyModalClass });
await modal.present(); // throws 'framework delegate is missing'

// after (bootstrap the framework, or use inline content)
// Angular: ensure IonicModule.forRoot() is imported in AppModule
// or use inline:
//   <ion-modal [isOpen]="true"><my-modal></my-modal></ion-modal>

// Ensure a delegate is available before presenting a controller-created overlay:
if (hasFrameworkDelegate) {
  const modal = await modalController.create({ component: MyModal });
  await modal.present();
} else {
  // use inline overlays, or pass a tag string / HTMLElement
}

function isFrameworkDelegateConfigured(): boolean {
  // framework integrations set a delegate; check via your framework's API
  // e.g. Angular: DelegateController available; React: IonReactDelegate present
  return true; // replace with real check
}

When it happens

Trigger: Presenting an overlay (modal/popover/loading/etc.) created via controller (e.g. modalController.create({ component: MyComp })) where component is a class reference, in a project that has not registered its framework delegate. Hascontroller is true for controller-created overlays, so the throw fires on present().

Common situations: Using @ionic/angular/@ionic/react/@ionic/vue controller APIs without installing/bootstrapping the framework package; SSR or unit tests that import overlay controllers directly from @ionic/core without a delegate; partial migration where the delegate provider was removed.

Related errors

• framework delegate is missing
• Invalid hour cycle "${hourCycle}"
• Invalid hour cycle "${hourCycle}"
• Hour value not found from DateTimeFormat
• Invalid hour cycle "${hourCycle}"

AI-assisted analysis of ionic-team/ionic-framework@625f9c38ad (2026-08-12). Data as JSON: /api/errors/80e4a14b20a26b98. Report an issue: GitHub.