ionic-team/ionic-framework · error · Error

framework delegate is missing

Error message

framework delegate is missing

What it means

Thrown by attachComponent() in framework-delegate.ts when no FrameworkDelegate was supplied, the call is not inline, and the component argument is neither a tag string nor an existing HTMLElement. In that situation Ionic has no way to materialize the component (it would need a framework's compiler/change-detection), so it aborts rather than appending undefined.

Source

Thrown at core/src/utils/framework-delegate.ts:19

import type { ComponentRef, FrameworkDelegate } from '../interface';

import { componentOnReady } from './helpers';

// TODO(FW-2832): types

export const attachComponent = async (
  delegate: FrameworkDelegate | undefined,
  container: Element,
  component?: ComponentRef,
  cssClasses?: string[],
  componentProps?: { [key: string]: any },
  inline?: boolean
): Promise<HTMLElement> => {
  if (delegate) {
    return delegate.attachViewToDom(container, component, componentProps, cssClasses);
  }
  if (!inline && typeof component !== 'string' && !(component instanceof HTMLElement)) {
    throw new Error('framework delegate is missing');
  }

  const el: any = typeof component === 'string' ? container.ownerDocument?.createElement(component) : component;

  if (cssClasses) {
    cssClasses.forEach((c) => el.classList.add(c));
  }
  if (componentProps) {
    Object.assign(el, componentProps);
  }

  container.appendChild(el);

  await new Promise((resolve) => componentOnReady(el, resolve));

  return el;
};

View on GitHub (pinned to 625f9c38ad)

Solutions

1. Provide the correct framework delegate (Angular: pass the DelegateController/Delegate; React: ensure IonReactDelegate wraps the app; Vue: install the Ionic Vue plugin so the delegate is registered).
2. If you intend a vanilla setup, pass component as a tag string (e.g. 'ion-custom-page') or a pre-built HTMLElement instead of a class reference.
3. For overlays, prefer inline usage (place the content as children of ion-modal/ion-popover) so attachComponent takes the inline path.
4. Verify the framework integration package (@ionic/angular, @ionic/react, @ionic/vue) is installed and bootstrapped before presenting overlays/nav.

Example fix

// before (vanilla, class reference, no delegate)
overlay.component = MyPageClass;
await overlay.present(); // throws 'framework delegate is missing'

// after (vanilla: pass an element or tag string)
overlay.component = document.createElement('ion-custom-page');
await overlay.present();

function canAttachWithoutDelegate(component: unknown, inline: boolean): boolean {
  return inline || typeof component === 'string' || component instanceof HTMLElement;
}
if (!delegate && !canAttachWithoutDelegate(component, inline)) {
  // pass a tag string / HTMLElement, or supply a framework delegate
}

function isAttachableComponent(c: unknown): c is string | HTMLElement {
  return typeof c === 'string' || c instanceof HTMLElement;
}

When it happens

Trigger: attachComponent is invoked with a component that is a class/component-reference object (not a string tag, not a DOM node) while delegate is undefined and inline is false. This is exactly what happens when a framework-less setup tries to mount a framework component, or when a delegate was expected but never wired (e.g. Angular DelegateController not provided, React/Vue bridge missing).

Common situations: Using ion-modal/ion-popover/ion-nav `component` property with a class reference in a vanilla or incorrectly-initialized project; SSR or test harness that doesn't register the framework delegate; migrating an app and forgetting to provide the Angular Delegate / React IonicReactDelegate / Vue delegate.

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/595d06163d307c4c. Report an issue: GitHub.