Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

TypeScript rejects createRoot(document.getElementById('root'))

ErrorArgument of type 'HTMLElement | null' is not assignable to parameter of type

Short answer

document.getElementById returns an element or null, and createRoot only accepts a real DOM element. With strictNullChecks on, TypeScript refuses the call. Check for null before the call, throw a clear error if the root is missing, or use the ! assertion only when the HTML file really has that id.

  • Applies to React 19, TypeScript 5.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Look at the line with createRoot in your entry file, and check that the HTML page really has an element with that id.

    grep -n "createRoot\|getElementById" src/main.tsx
    grep -n 'id="root"' index.html
  2. 2Match what you see, then jump to its fix

    1. 1TS2345 on the createRoot line, while the app runs fine in the browser.strictNullChecks is on and the null case is not handledFix
    2. 2The null check above hides a wrong id: the app compiles and then shows nothing.You want a loud failure instead of a silent blank pageFix
    3. 3The guard throws at runtime although the id matches.The script runs before the root element existsFix

What does the error look like?

  • Argument of type 'HTMLElement | null' is not assignable to parameter of type
  • Type 'null' is not assignable to type ... ts(2345)
  • Type 'null' is not assignable to type 'Element | DocumentFragment'
  • Target container is not a DOM element

Cause 1 of 3

strictNullChecks is on and the null case is not handled

1Check

getElementById is documented to return null when no element matches. With strictNullChecks on, TypeScript requires you to test for null before using the value, so the call is a type error even if the element exists at runtime.

grep -n strict tsconfig*.json

2Fix

Narrow the value before the call.

const container = document.getElementById('root');
if (container) {
  createRoot(container).render(<App />);
}

3Verify

The type checker passes.

npx tsc --noEmit

Confirmed by typescriptlang.org

Did this fix it?

Cause 2 of 3

You want a loud failure instead of a silent blank page

1Check

The lookup is case-sensitive, and returns null when the element is not in the document. A typo in the id, or a different id in index.html, silently skips the render.

grep -n 'id=' index.html

2Fix

Throw when the root is missing, so the real problem shows up at once.

const container = document.getElementById('root');
if (!container) throw new Error('Root element #root not found');
createRoot(container).render(<App />);

3Verify

Rename the id in index.html on purpose and see your own error message; then restore it.

npm run dev

Confirmed by developer.mozilla.org

Did this fix it?

Cause 3 of 3

The script runs before the root element exists

1Check

React's createRoot reference says the bundle's script tag cannot see DOM nodes that appear after it in the HTML, and the container is then null.

grep -n 'script\|id="root"' index.html

2Fix

Place the script tag after the element, or run the code once the DOM is ready. Use the ! assertion only when you know the element exists: it changes the type, not the runtime behaviour.

<div id="root"></div>
<script type="module" src="/src/main.tsx"></script>

3Verify

The page renders and the console shows no error.

npm run build

Confirmed by react.dev

Did this fix it?

How do I stop it coming back?

  • Keep strictNullChecks on and handle the null once, in the entry file.
  • Use a guarded throw rather than the ! assertion for the root element.
  • Keep the id in index.html and the code in one obvious place.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Web apps

TypeScript rejects MUI Data Grid columns that set a type

A TypeScript error inside a column's renderCell callback

A columns array declared without a type is inferred with type as a plain string, which the Data Grid's column type union does not accept.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.