Debugging a page

A page inside Minecraft has no address bar, no reload button and no inspector, so when it comes up blank there is nowhere obvious to look. This page is that place.

Everything here is client-side: it is a setting on the machine running the page, not something a server turns on for its players.

The settings screen

WebGUI has one screen of its own, reached from the game's own mod list:

Loader	How to get there
NeoForge	Mods → WebGUI → Config
Fabric	Mods (Mod Menu) → WebGUI → the config button

Fabric has no mod list of its own, so on Fabric this needs Mod Menu. Without it the same setting can be written by hand — see the config file below.

Settings are saved the moment you change them, into config/webgui/client.json.

Page developer tools

Turn this on and Chromium's own view of the page goes into the game log — the same information a browser's DevTools console shows you:

[JCEF-Lifecycle/INFO]  (webgui) webgui devtools: watching http://127.0.0.1:25580/88cd…/index.html
[JCEF-Lifecycle/WARN]  (webgui) webgui devtools: console.warning: a warning from the page  at index.html:60
[JCEF-Lifecycle/ERROR] (webgui) webgui devtools: [network] Failed to load resource: the server
    responded with a status of 404 (Not Found)  http://127.0.0.1:25580/88cd…/missing-on-purpose.png
[JCEF-Lifecycle/ERROR] (webgui) webgui devtools: uncaught Error: deliberate failure  at inner index.html:44

Specifically:

• console.log, console.warn, console.error with the file and line that made the call, and the game log level matched to the console level.
• Uncaught exceptions, with the message and where they were thrown — including the ones that happen before your own error handling is set up.
• Failed requests, with the URL and the status: a 404 for a file you misspelled, a 500 from your API, a request that never connected.
• Browser warnings you would otherwise never see: blocked mixed content, CORS refusals, deprecations.

It works for any page, whether the server hosts it or your own domain does.

This is for developing, not for playing

It is off by default and there is no reason for a player to turn it on: a chatty page makes the log large, and no page needs it to work. Turn it on while you are building a page, and back off afterwards.

At most 20 messages a second are written; past that the rest of the second is dropped with one line saying so, so a page in a loop cannot fill the disk.

The full inspector, in your own browser

Chromium's remote debugging port gives you the real DevTools — DOM tree, Network panel, Sources with breakpoints — attached to the page running inside the game. Add one game argument where your launcher lets you pass them:

--remote-debugging-port=9222

Then open http://127.0.0.1:9222 in Chrome (or chrome://inspect → Configure → add 127.0.0.1:9222), and pick the page. It is the same inspector you would get on a normal site.

The mod cannot turn this on for you: the switch is read when Chromium starts, from the command line of the process, which is fixed before any mod runs. WebGUI's settings screen does tell you whether it is on and prints the address when it is.

It is a debugging port, not a private one

Anything that can reach that port can drive the browser inside your game. It is bound to loopback, so nothing on the network can, but leave it off unless you are using it.

Where the argument goes

This is a game argument, not a JVM argument — it goes after the main class, alongside --username and friends, and the game passes what it does not recognise straight through. Not every launcher exposes a field for game arguments; in a Gradle development environment it is runClient --args="--remote-debugging-port=9222".

What is always in the log, without any setting

• console.* from the page. Already forwarded, and has been for a long time — the developer-tools setting adds the file, the line and the stack, not the message itself.

• Files a bundled page asked for and did not get, with what to do about it:

  webgui: page asset /assets/app.js was requested without this session's prefix, so it
  cannot be served. A build that emits absolute paths like /assets/app.js does this -
  rebuild it with a relative base (Vite base: './', CRA homepage: '.').
  Requested by: http://127.0.0.1:25580/df55…/index.html

  Each distinct path is reported once. See Pages the server hosts.

Where the log is

Launcher	File
Vanilla launcher	.minecraft/logs/latest.log
Prism / MultiMC	the instance's Minecraft Log tab, or <instance>/minecraft/logs/latest.log
Modrinth App	<profile>/logs/latest.log

Lines from this feature all start with webgui, so latest.log filtered on that word is usually the whole story.

The config file

config/webgui/client.json, next to the server's own config:

{
  "devTools": false
}

Written whenever a setting changes, and read at startup. Editing it by hand works — that is the way in on Fabric without Mod Menu — but the game reads it once, at launch, so restart after editing.

What this is not

The Page developer tools setting is not the DevTools window: there is no DOM tree to click through, no Sources tab, no breakpoints. It reads Chromium's DevTools protocol, which needs no window and no port — which is why it works with nothing but a toggle, while the inspector needs the launch argument above.

Use the toggle when you want a page's errors in the log without setting anything up, and the remote debugging port when you want to actually inspect the page.