angular/components · error

Attempting to attach a portal to a null PortalOutlet

Error message

Attempting to attach a portal to a null PortalOutlet

What it means

Thrown by the Angular CDK Portal API when code calls attach() on a Portal with a host that is null or undefined. The library requires a valid PortalOutlet (usually a DomPortalOutlet or a component/.directive implementing CdkPortalOutlet) before a portal can be attached, so attaching to nothing is a programming mistake and is rejected immediately in dev mode.

Source

Thrown at src/cdk/portal/portal-errors.ts:49

}

/**
 * Throws an exception when attempting to attach an unknown portal type.
 * @docs-private
 */
export function throwUnknownPortalTypeError() {
  throw Error(
    'Attempting to attach an unknown Portal type. BasePortalOutlet accepts either ' +
      'a ComponentPortal or a TemplatePortal.',
  );
}

/**
 * Throws an exception when attempting to attach a portal to a null host.
 * @docs-private
 */
export function throwNullPortalOutletError() {
  throw Error('Attempting to attach a portal to a null PortalOutlet');
}

/**
 * Throws an exception when attempting to detach a portal that is not attached.
 * @docs-private
 */
export function throwNoPortalAttachedError() {
  throw Error('Attempting to detach a portal that is not attached to a host');
}

View on GitHub (pinned to 0411926e7d)

Solutions

1. Ensure the PortalOutlet exists and is initialized before calling attach — attach after the view is initialized (ngAfterViewInit) or inside a ngAfterViewInit/afterNextRender callback
2. Check for null before attaching: if (outlet) portal.attach(outlet)
3. If the outlet is inside an *ngIf, guarantee it is rendered (or use a always-present container) before attaching
4. If the outlet may be destroyed/recreated, re-resolve the reference (e.g. via @ViewChild query) before each attach

Example fix

// before
@ViewChild(CdkPortalOutlet) outlet: CdkPortalOutlet;
ngOnInit() {
  this.portal.attach(this.outlet); // outlet may be undefined here
}
// after
@ViewChild(CdkPortalOutlet) outlet: CdkPortalOutlet;
ngAfterViewInit() {
  if (this.outlet) {
    this.portal.attach(this.outlet);
  }
}

if (!outlet) {
  throw new Error('Cannot attach portal: outlet is null. Attach after the view is initialized (ngAfterViewInit).');
}
portal.attach(outlet);

function hasOutlet(outlet: PortalOutlet | null | undefined): outlet is PortalOutlet {
  return outlet != null;
}

try {
  portal.attach(outlet);
} catch (e) {
  if (e instanceof Error && e.message.includes('null PortalOutlet')) {
    console.warn('Portal outlet not ready; retrying after view init');
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling portal.attach(outlet) where the outlet argument is null/undefined; calling attach() on a CdkPortalOutlet whose host view container has not been initialized yet; resolving an outlet reference (e.g. @ViewChild) before the view is rendered.

Common situations: Attaching a portal in ngOnInit or a constructor before the outlet's view is created; a template conditional (ngIf) removing the <ng-template cdkPortalOutlet> element; forgetting to pass the outlet argument; a destroyed outlet still referenced by code.

Related errors

• Cannot attach component portal to outlet without an Applicat
• DOM portal content must be attached to a parent node.
• DOM portal content must be attached to a parent node.
• Must provide a portal to attach
• Host already has a portal attached

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/4c4d76f92916066e. Report an issue: GitHub.