How to fix Expected container to be an Element, a Document or a DocumentFragment in React

ReactINTERMEDIATEMEDIUM

This error occurs when you pass an invalid container type to React Testing Library queries or render functions. The container must be a valid DOM Element, Document, or DocumentFragment, but you're providing something else like null, undefined, a string, or an incorrect object type.

What this error means

React Testing Library requires a valid DOM container to render components into and query elements from. When you pass an invalid container (not an Element, Document, or DocumentFragment), the library cannot establish a proper testing environment. This error typically happens when manually creating containers incorrectly, using the wrong API methods, or passing containers that have been unmounted or are no longer in the DOM.

How to fix "Expected container to be an Element, a Document or a DocumentFragment"

1Ensure container is a valid DOM element

When creating a custom container, make sure it's a proper DOM element appended to the document:

javascript

// Correct way to create a container
const container = document.createElement('div');
document.body.appendChild(container);

// Use it with render
const { unmount } = render(<MyComponent />, { container });

// Clean up after test
unmount();
document.body.removeChild(container);

Never pass null, undefined, or strings as containers.

2Use default container (avoid custom containers when possible)

React Testing Library automatically creates a container for you. Avoid custom containers unless absolutely necessary:

javascript

// Usually you don't need a custom container
const { getByText } = render(<MyComponent />);
const element = getByText('Submit');

// Only use custom containers for specific edge cases
const table = document.createElement('table');
document.body.appendChild(table);
render(<TableBody />, { container: table });

Most tests work fine with the default container.

3Check for null/undefined container references

Ensure your container reference exists and is valid:

javascript

// BAD: container might be null
const container = document.querySelector('.non-existent');
render(<MyComponent />, { container }); // Error!

// GOOD: check for existence
const container = document.querySelector('.my-container');
if (!container) {
  throw new Error('Container not found');
}
render(<MyComponent />, { container });

// BETTER: create container if it doesn't exist
let container = document.querySelector('.my-container');
if (!container) {
  container = document.createElement('div');
  container.className = 'my-container';
  document.body.appendChild(container);
}

4Avoid using container after unmount

Once a component is unmounted, its container might become invalid. Don't reuse containers:

javascript

// BAD: reusing unmounted container
const container = document.createElement('div');
document.body.appendChild(container);

const { unmount } = render(<Component1 />, { container });
unmount();

// This will fail - container was cleaned up
render(<Component2 />, { container });

// GOOD: create fresh container for each test
beforeEach(() => {
  container = document.createElement('div');
  document.body.appendChild(container);
});

afterEach(() => {
  document.body.removeChild(container);
  container = null;
});

5Use screen queries instead of container-bound queries

Prefer screen queries which use document.body as the default container:

javascript

// BAD: might have container issues
const { container } = render(<MyComponent />);
const element = getByText(container, 'Submit');

// GOOD: use screen which is always available
render(<MyComponent />);
const element = screen.getByText('Submit');

// Also GOOD: use destructured queries from render
const { getByText } = render(<MyComponent />);
const element = getByText('Submit');

screen queries avoid container reference issues entirely.

How to fix Expected container to be an Element, a Document or a DocumentFragment in React

What this error means

Typical symptoms

Common causes

How to fix "Expected container to be an Element, a Document or a DocumentFragment"

Advanced notes

Related errors

Official resources & further reading