angular/components · error

Must provide a portal to attach

Error message

Must provide a portal to attach

What it means

`throwNullPortalError` is called by BasePortalOutlet.attach when a null/undefined portal is passed. The outlet has nothing to render, so the library fails fast with a clear message instead of a downstream null dereference.

Source

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

/**
 * @license
 * Copyright Google LLC All Rights Reserved.
 *
 * Use of this source code is governed by an MIT-style license that can be
 * found in the LICENSE file at https://angular.dev/license
 */

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

/**
 * Throws an exception when attempting to attach a portal to a host that is already attached.
 * @docs-private
 */
export function throwPortalAlreadyAttachedError() {
  throw Error('Host already has a portal attached');
}

/**
 * Throws an exception when attempting to attach a portal to an already-disposed host.
 * @docs-private
 */
export function throwPortalOutletAlreadyDisposedError() {
  throw Error('This PortalOutlet has already been disposed');
}

View on GitHub (pinned to 0411926e7d)

Solutions

1. Guard before attaching: `if (portal) outlet.attach(portal)`
2. Ensure the @Input()/async data producing the portal is resolved before attach
3. Fix the lookup expression that returns null/undefined
4. Centralize attachment in a helper that validates the portal argument

Example fix

// before
this.outlet.attach(this.activePortal); // activePortal can be undefined
// after
if (this.activePortal) { this.outlet.attach(this.activePortal); }

function attachSafe(outlet: PortalOutlet, portal: Portal<any> | null | undefined): void {
  if (portal) { outlet.attach(portal); }
}

function isPortal(v: unknown): v is Portal<any> {
  return v instanceof Portal;
}

try {
  outlet.attach(portal!);
} catch (e) {
  if (e.message === 'Must provide a portal to attach') {
    console.warn('No portal available; skipping attach');
  } else { throw e; }
}

When it happens

Trigger: Calling `outlet.attach(null)` / `attach(undefined)`, or passing a variable that is undefined due to a failed lookup (e.g. `this.portals[key]` or an unresolved service member).

Common situations: Dynamic portal lookup returning undefined; a portal input @Input() not yet set when attach runs; optional chaining / async data not loaded before attach; refactors renaming the portal field.

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.
• Host already has a portal attached
• This PortalOutlet has already been disposed

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