AUR0812

Error Message

AUR0812: Invalid portal strict target resolution, target not found.

Description

This error occurs when using the portal custom attribute in strict mode (e.g., portal="strict: <selector>" or portal.strict="<selector>") and the provided CSS selector, while valid and non-empty, fails to find a matching element within the document.body.

Cause

The strict mode for portals requires that the specified CSS selector resolves to exactly one element currently present in the document.body. This error signifies that document.body.querySelector(<selector>) returned null.

Common causes include:

1. Typo in Selector: The CSS selector is misspelled or does not accurately target the intended element.

2. Target Element Missing: The element matching the selector does not exist in the DOM when the portal attempts to find it. This could be due to timing issues (portal tries to attach before the target is rendered) or the element simply not being part of the page structure.

3. Target Element Not in document.body: The strict mode specifically searches within document.body. If the target element exists but is outside the body (which is uncommon but possible in detached DOM fragments or shadow roots not attached to the body), it won't be found by this specific mechanism.

Solution

1. Verify Selector: Double-check the CSS selector for typos and ensure it correctly identifies the intended target element. Use browser developer tools (document.body.querySelector('<your-selector>')) to test the selector directly in the console.

2. Ensure Target Exists: Confirm that the target element exists in the document.body before the portal element tries to attach and render its content. You might need to adjust rendering order or use lifecycle hooks (attached) to delay portal activation if necessary.

3. Use Non-Strict Mode: If the target might not always exist or if strict resolution isn't critical, consider using non-strict targeting modes:

   • portal="target:<selector>": Appends to the target if found, otherwise appends to document.body.

   • portal.bind="targetElement": Binds directly to an element reference.

   • portal (no value): Appends to document.body.

Example

<!-- Assume #my-portal-target does NOT exist in the body -->
<!-- Incorrect: Strict mode selector finds nothing -->
<div portal="strict: #my-portal-target">Portal Content</div>

<!-- Assume targetSelector points to a non-existent element ID -->
<!-- Incorrect: Bound strict selector finds nothing -->
<template>
  <div portal.strict.bind="targetSelector">Portal Content</div>
</template>

<!-- Correct: Ensure the target element exists -->
<div id="actual-portal-target"></div>
<div portal="strict: #actual-portal-target">Portal Content</div>

<!-- Correct: Using non-strict mode might be acceptable -->
<div portal="target: #maybe-portal-target">Portal Content (appends to body if target missing)</div>

// View Model Example
import { customElement } from 'aurelia';

@customElement({ /* ... */ })
export class MyComponent {
  // Incorrect setup for the binding example above if #non-existent-target is not in the DOM
  targetSelector = '#non-existent-target';

  // Correct setup requires element #actual-portal-target to exist in the body
  // targetSelector = '#actual-portal-target';
}

Debugging Tips

• Use the browser's developer console to execute document.body.querySelector('<your-selector>') and verify it returns the expected element and not null.

• Inspect the DOM structure when the error occurs to confirm the target element's presence and its ID/class/attributes match the selector.

• Check for timing issues. Set breakpoints before the portal attaches to see if the target element has been rendered yet.

• Temporarily switch to portal="target:<selector>" to see if the portal content renders (it should append to the body if the target is missing), confirming the issue is target resolution.