Fix Error: Target container is not a DOM element. in React

This error fires when ReactDOM.createPortal or ReactDOM.render targets a DOM element that does not exist yet. The element may be missing from the HTML, the script may run before the DOM is ready, or the portal target ID is misspelled. Fix it by ensuring the target element exists in the HTML before the portal renders, or by deferring portal rendering to useEffect.

Reading the Stack Trace

Here's what each line means:

• at createPortal (node_modules/react-dom/cjs/react-dom.development.js:254:11): ReactDOM.createPortal throws because the target container passed to it is null, not a valid DOM element.
• at Modal (webpack-internal:///./src/components/Modal.tsx:10:10): Modal.tsx line 10 calls createPortal with document.getElementById('modal-root'), which returns null because the element does not exist.
• at mountIndeterminateComponent (node_modules/react-dom/cjs/react-dom.development.js:20069:13): The component is mounting for the first time and immediately crashes because the portal target is missing.

Common Causes

// index.html only has <div id="root"></div>
// Missing <div id="modal-root"></div>

export default function Modal({ children }) {
  return createPortal(
    <div className="modal">{children}</div>,
    document.getElementById('modal-root')!
  );
}

// HTML has: <div id="modal-root"></div>
// Component uses wrong ID:
const target = document.getElementById('modalRoot');
return createPortal(<div>{children}</div>, target!);

export default function Modal({ children }) {
  const target = document.getElementById('modal-root');
  return createPortal(<div>{children}</div>, target!);
}

The Fix

Defer the portal target lookup to useEffect, which only runs on the client after the DOM is ready. If the target element does not exist, create it dynamically. Render null until the container is available, preventing the crash entirely.

export default function Modal({ children }) {
  return createPortal(
    <div className="modal">{children}</div>,
    document.getElementById('modal-root')!
  );
}

import { createPortal } from 'react-dom';
import { useState, useEffect } from 'react';

export default function Modal({ children }: { children: React.ReactNode }) {
  const [container, setContainer] = useState<HTMLElement | null>(null);

  useEffect(() => {
    let el = document.getElementById('modal-root');
    if (!el) {
      el = document.createElement('div');
      el.id = 'modal-root';
      document.body.appendChild(el);
    }
    setContainer(el);
  }, []);

  if (!container) return null;

  return createPortal(
    <div className="modal">{children}</div>,
    container
  );
}

Testing the Fix

import { render, screen } from '@testing-library/react';
import Modal from './Modal';

describe('Modal', () => {
  afterEach(() => {
    const el = document.getElementById('modal-root');
    if (el) el.remove();
  });

  it('creates modal-root if missing', () => {
    render(<Modal>Hello</Modal>);
    expect(document.getElementById('modal-root')).toBeInTheDocument();
  });

  it('renders children into the portal', () => {
    render(<Modal><p>Modal content</p></Modal>);
    expect(screen.getByText('Modal content')).toBeInTheDocument();
  });

  it('does not crash when rendered on the server', () => {
    expect(() => render(<Modal>Test</Modal>)).not.toThrow();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/react-portal-target-error,git add src/components/Modal.tsx src/components/__tests__/Modal.test.tsx,git commit -m "fix: defer portal target lookup to useEffect and create if missing",git push origin fix/react-portal-target-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npm run build

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

import { initBugStack } from 'bugstack-sdk'

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Run the test suite locally to confirm the portal renders correctly.
2. Open a pull request with the deferred portal target lookup.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify modals work in staging.

Frequently Asked Questions