Debug FiveM NUI: nui_devtools, console errors and failed callbacks

Your NUI opens as a blank panel, a button does nothing, or the cursor appears and no screen follows. There is usually no Lua error, because the fault is in the web page. You need the browser console, and FiveM has one. This guide covers how to open it, how to read its errors and how to test your UI without the game.

#Open the devtools: nui_devtools

NUI is a Chromium page inside the game. Press F8 to open the FiveM console and run:

nui_devtools

A devtools window opens for the NUI layer, like the one you know from a browser. Use these tabs:

• Console: JavaScript errors and your own console.log lines.
• Network: every request the page makes, including the callbacks to Lua.
• Elements: the live HTML and CSS. Use it to see whether your element exists, how large it is and whether it is hidden.
• Sources: set breakpoints in your script.

Warning: whether nui_devtools is available depends on your settings and on the client build you run. If the command does nothing, check that your game client is up to date, and test the UI in a normal browser as shown below.

If your UI is visible only after a SendNUIMessage, open the devtools first and trigger the action afterwards, so you see the messages that arrive.

#Read the console errors

Errors in the Console tab show the file and the line of your script. The ones you will see most:

Uncaught TypeError: Cannot read properties of undefined (reading 'items')

Your code read .items on something that is undefined. In NUI this almost always comes from the message:

window.addEventListener('message', (event) => {
  const { action, data } = event.data
  if (action === 'open') {
    render(data.items)   // data is undefined
  }
})

Check what Lua really sent. Print the whole message first:

window.addEventListener('message', (event) => {
  console.log('NUI message', JSON.stringify(event.data))
})

Then compare it to the Lua call:

SendNUIMessage({ action = 'open', data = { items = items } })

The keys must match exactly, including case. A field set to nil in Lua is missing from the message, so it is undefined in JavaScript.

Other common errors:

If the Network tab shows a 404 for your JS, CSS or images, add every file the page loads to files in the manifest, and point ui_page to the right HTML:

ui_page 'web/index.html'

files {
  'web/index.html',
  'web/**/*',
}

For a Vite or React build, use the output folder, see FiveM NUI with React and Vite.

#Failed fetch to https://resource/cb

NUI sends messages to Lua with a request to https://<resource name>/<callback name>:

fetch(`https://${GetParentResourceName()}/close`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({}),
})

In the Network tab a failed request shows in red:

POST https://my_script/close net::ERR_FAILED

Check these in order:

1. The callback is not registered. The name after the slash must match a RegisterNUICallback on the client, exactly:

RegisterNUICallback('close', function(data, cb)
    SetNuiFocus(false, false)
    cb('ok')
end)

2. The resource name is wrong. The host in the URL is the resource folder name. If you renamed the folder, a hard-coded https://old_name/close fails. Use GetParentResourceName() in the page, as above, so the name follows the folder.
3. The callback never answers. Always call cb(...), even with cb('ok'). A handler that returns without calling it leaves the request pending, and the page can wait forever.
4. The Lua handler errors before cb. Check the F8 console for a script error at the same moment. An error before cb means the answer is never sent.
5. The resource is not running. Callbacks live as long as the client script that registered them.

#Focus and the cursor

If the UI shows but cannot be clicked, or the mouse stays stuck after closing, the problem is SetNuiFocus, not the page. See NUI focus stuck cursor.

#Test the UI in a normal browser

Debugging in game is slow. Most of a NUI can be tested in a browser, with your editor's live reload.

Open index.html through a local server, or run npm run dev for a Vite project. Then stub the two things the game normally provides.

First, a fake GetParentResourceName, and callbacks that do not fail:

if (!window.GetParentResourceName) {
  window.GetParentResourceName = () => 'my_script'
  window.fetch = async (url, options) => {
    console.log('NUI callback', url, options && options.body)
    return { ok: true, json: async () => ({}) }
  }
}

Second, send the messages that Lua would send. From the browser console, or a dev-only button:

window.postMessage({ action: 'open', data: { items: [{ name: 'water', count: 3 }] } }, '*')

This calls your message listener exactly as SendNUIMessage does. You can design, fix layout and check data handling in the browser, and keep the game for the final check of focus, real data and real callbacks.

Tip: remove the stubs from the production build, or wrap them so they only run when the page is opened outside the game, as above with the if on GetParentResourceName.

#Checklist