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

ReactINTERMEDIATEMEDIUMUpdated Dec 10, 2025· 111 views

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.

Quick fix

Fixes Expected container to be an Element, a Document or a DocumentFragment

// 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);
  1. Ensure container is a valid DOM element
  2. Use default container (avoid custom containers when possible)
  3. Check for null/undefined container references
  4. Avoid using container after unmount
react — error
// 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);
Expected container to be an Element, a Document or a DocumentFragment

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.

Typical symptoms

  • Tests fail with the error message "Expected container to be an Element, a Document or a DocumentFragment"
  • render() calls fail even when the component seems correct
  • Queries return errors about invalid containers
  • Custom container setups using document.createElement() might be incorrect
  • Container references become null or undefined after component unmounting

Common causes

  1. Passing null or undefined as a container to render() or queries
  2. Using a string (like a CSS selector) instead of a DOM element
  3. Passing a React component or JSX element instead of a DOM element
  4. Container element was removed from the DOM before being used
  5. Using document.createElement() but not appending it to the document
  6. Passing the wrong type of DOM node (e.g., Text node instead of Element)
  7. Container reference becomes stale after component unmounts

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.

Advanced notes

This error highlights an important Testing Library principle: test like a user. Users don't interact with containers or DOM nodes directly—they interact with rendered UI. If you find yourself needing custom containers frequently, reconsider your testing approach. Most components should be testable with the default container. The error also serves as a type safety check—TypeScript can catch many of these issues if you have proper type definitions. For complex cases like testing within iframes or shadow DOM, you may need custom containers, but ensure they're properly set up with valid DOM elements.

Frequently asked questions

What does "Expected container to be an Element, a Document or a DocumentFragment" mean?
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 do I fix "Expected container to be an Element, a Document or a DocumentFragment"?
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 causes "Expected container to be an Element, a Document or a DocumentFragment"?
Passing null or undefined as a container to render() or queries Using a string (like a CSS selector) instead of a DOM element Passing a React component or JSX element instead of a DOM element
Is the "Expected container to be an Element, a Document or a DocumentFragment" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading