AUR0768

Error Message

AUR0768: An instance of Aurelia is already registered with the container or an ancestor of it.

Description

This error occurs when you attempt to create a new Aurelia instance (e.g., new Aurelia(container)) but the provided dependency injection (DI) container, or one of its parent containers, already has an instance of Aurelia registered with it. Each Aurelia application should typically have its own distinct DI container hierarchy, and this error prevents accidentally creating nested or conflicting application instances within the same hierarchy.

Cause

1. Creating Multiple Aurelia Instances with the Same Container: Explicitly creating new Aurelia(container) more than once, passing the exact same container instance each time.

2. Creating Aurelia Instance with a Child Container: Creating a child container (const childContainer = container.createChild()) from a container that already belongs to an Aurelia instance, and then attempting to create a new Aurelia instance with that child container (new Aurelia(childContainer)). The constructor checks ancestor containers as well.

3. Accidental Re-initialization: Code logic that inadvertently tries to initialize and start an Aurelia application multiple times without properly disposing of the previous instance and container.

Solution

1. Use a Single Aurelia Instance: Ensure that your application logic creates and manages only one Aurelia instance for a given DI container hierarchy. Store the instance if it needs to be referenced later, rather than creating a new one.

2. Use Separate Containers for Separate Apps: If you genuinely need multiple, independent Aurelia applications running concurrently (e.g., micro-frontends), ensure each one is created with a completely separate root DI container (new Container()). Do not share containers or use child containers across these independent applications.

3. Proper Disposal: If you need to stop and restart an Aurelia application (uncommon), ensure you call aurelia.dispose() on the old instance before creating a new one with a fresh container.

Example

import Aurelia from 'aurelia';
import { DI, IContainer } from '@aurelia/kernel';

// Scenario 1: Reusing the same container
const container = DI.createContainer();
const aurelia1 = new Aurelia(container); // OK

// Incorrect: Trying to create another Aurelia instance with the same container
try {
  const aurelia2 = new Aurelia(container); // Throws AUR0768
} catch (e) {
  console.error(e.message); // Logs the AUR0768 error
}

// Scenario 2: Using a child container
const rootContainer = DI.createContainer();
const app1 = new Aurelia(rootContainer); // OK

const childContainer = rootContainer.createChild();
// Incorrect: Trying to create a new Aurelia instance with a child container
try {
  const app2 = new Aurelia(childContainer); // Throws AUR0768
} catch (e) {
  console.error(e.message); // Logs the AUR0768 error
}

// Correct approach for multiple independent apps:
const containerA = DI.createContainer();
const aureliaA = new Aurelia(containerA);
// ... configure and start aureliaA

const containerB = DI.createContainer();
const aureliaB = new Aurelia(containerB);
// ... configure and start aureliaB (independent)

Debugging Tips

• Examine the code where new Aurelia(...) is called.

• Identify the container instance being passed to the constructor.

• Check if that specific container instance (or any of its ancestors) has been used previously to create another Aurelia instance.

• Use logging or debugging to track the lifecycle of your DI containers and Aurelia instances, especially if you suspect accidental re-initialization.

• If using child containers, visualize the container hierarchy to understand potential conflicts.