# 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

```typescript
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aurelia.io/developer-guides/error-messages/runtime-html/aur0768.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.