Troubleshooting the editor
Editor docs
What to look at when something goes wrong: the editor's local crash reports, the project's private
.ignifx/ folder, and the reasons the editor refuses to start a project's MCP server. The editor is
a preview.
Crash reports#
When something crashes, the editor writes a report to disk and sends nothing anywhere: the
editor has no telemetry and no upload. Help → Open Crash Reports Folder opens the folder, which
is crashes/ in the editor's user data (on macOS, under ~/Library/Application Support/).
A report is one JSON file, crash-<UTC time>-<process>-<n>.json, for an uncaught error in the
editor's main process, a lost window or child process, or an unhandled error in the window. It
holds the editor and engine versions, the platform, the error and its stack, and the Console's last
200 lines. Your project appears only as its folder name and a short hash of its path; paths inside
the project become <project>, your home folder ~, and tokens and keys are removed. The newest 50
reports are kept. Native crash dumps land in the same folder.
If the editor window crashes, it reloads once and shows a strip naming the reason and the report, never a dialog. Your open scene, its unsaved edits and its undo history live outside the window and survive the reload. A window that crashes again within a minute is not reloaded again.
To report a problem, attach the report file. Read it first: it is plain JSON and you decide what to share.
The .ignifx/ folder#
The editor keeps a project's private, machine-local files in .ignifx/ at the project root. It
writes a .gitignore holding * inside it, so git ignores the folder, and the engine's Vite plugin
refuses to serve it.
| File | What it is |
|---|---|
mcp.json | The running MCP server's port, token and process id, for the shim. Exists while the server runs. |
mcp-tools-cache.json | The last tool list, so an agent that starts before the editor still sees the tools. |
logs/mcp-YYYY-MM-DD.jsonl | The MCP audit log. |
Never commit .ignifx/, share mcp.json or paste its token anywhere. The editor never edits your
project's own .gitignore.
Some things are not in the project at all: the list of trusted folders, which projects have MCP switched on, recent projects and your external code editor live in the editor's own user data.
"MCP refused": the dev server serves .ignifx#
.ignifx/mcp.json holds the MCP server's token, and anything your dev server serves can be read by
a web page. So before the MCP server starts, and again whenever the project's dev server starts, the
editor asks that dev server for a file under .ignifx/ in every form a Vite server could return it.
If any answer contains it, or the dev server cannot be reached to check, the editor refuses to run
the MCP server. The status bar then reads MCP refused with the reason, and the Console says
more.
To fix it, make sure the project's vite.config.ts uses the engine's Vite plugin, ignifx() from
@ignifx/vite-plugin, at a current version: it refuses to serve .ignifx/ on the dev server. Every
template has it. Then switch MCP on again with File → MCP Server.
The check covers the standard paths only. A link or a custom middleware that serves .ignifx/ some
other way is not caught, so do not add one.
Other common problems#
- The project does not open. If you answered Don't Open to the trust question, nothing was started; open it again to be asked again. The welcome panel says why an open failed.
- The scene view stays empty. The dev server must be running: the status bar shows its state, and the Console shows the install and dev-server output. A project's dev server is restarted automatically once after a crash; after that, fix the error the Console shows and reopen the project.
- Play does not start. The game's entry must call
attachEditorPlayControls(app)fromvirtual:ignifx/editor, as the templates do. See Play mode. - An agent says the editor is down. Open the project in the editor and switch MCP on (File → MCP Server); the shim reconnects by itself.