Troubleshooting Common Issues

This page collects the most frequently reported problems and their solutions. Each section starts with the symptom or the exact error message, followed by the cause and the fix.

If your problem is not listed here, check the log files for errors and see Nothing Helped? below for support channels.

Editor Fails to Launch or Gets Stuck Loading 

Symptom: The editor window (or browser tab) never finishes loading, or the launch fails with a timeout error. Sometimes a retry succeeds.

Common causes and fixes, in order of likelihood:

Large game data file exceeds the launch timeout. The plugin waits a limited time (30 seconds by default) for the editor process to load the game data. For large files, increase the Idle Close Timeout in the Unity project settings: Edit → Project Settings → Charon.
VPN or proxy software interferes with local connections. The editor is a local web application served on localhost. Some VPN clients and system-wide proxies intercept or block this traffic. Temporarily disable them and retry.
A stale editor process is holding the port. Restart the Unity/Unreal editor. If that does not help, restart the computer to clear orphaned processes.
Unreal Engine plugin: the randomly chosen port is unavailable. The editor picks a random local port on each launch, and sometimes that port is already taken or blocked by OS permissions. Simply close and reopen the Charon window - a new port is picked on the next launch. Check the Output Log console for error messages if the problem persists.

If the problem persists, collect the log files and repeat the launch with verbose logging enabled.

Web UI Shows “Http failure response for api/v1/context/: 0 Unknown Error”

Symptom: The editor page opens but fails with the error above, while the same project may work in another git branch or after a reboot.

This indicates that the browser could not reach the local editor process at all. Try in order:

Hard-refresh the page and clear the cache: Ctrl+F5 or Ctrl+Shift+R.
Disable browser extensions (ad blockers and privacy tools are frequent offenders).
Disable VPN/proxy software.
Restart the Unity/Unreal editor, then the computer.

If the error reoccurs, save the log files from the failing session and send them to support - this class of problem is hard to reproduce and logs are essential.

Blank Page or Extension Fails to Load 

Symptom: The editor opens as a blank page, or an installed extension (custom document editor, property editor) does not appear as an option in the UI.

Hard-refresh and clear the browser cache: Ctrl+F5 or Ctrl+Shift+R.
Open the browser developer console (F12) and check for errors. A crashed or blocking browser extension is often visible at the top of the console output.
Try a private/incognito window or another browser to rule out browser extensions.
For Charon extensions: open Project Settings → Extensions and verify the package downloaded successfully (hover over the status icon, click Recheck if needed).
Verify your browser is supported: Chrome released 2021 or later, Firefox released 2023 or later. Other Chromium-based browsers (Edge, Opera, Brave…) should be a recent version.

Game Data File Is Corrupted After Version Control Operations 

Symptom: After a merge, rebase, or branch switch, Charon reports that the game data file is corrupted or is not valid JSON.

The file most likely contains unresolved merge conflict markers (<<<<<<<, =======, >>>>>>>). Charon detects Git, Mercurial, and SVN working copies and reloads the game data on checkouts, but it does not detect merge conflicts inside the file - a file with conflict markers is simply no longer valid JSON.

Fix:

For JSON game data: resolve the conflict with your usual text merge tools, the same way as for source code.
For binary formats (MessagePack): merging is not possible. Choose the correct side of the conflict entirely (ours or theirs) and re-apply the other side’s changes in the editor.

Note

JSON is the default storage format precisely because it can be diffed and merged in version control. Keep binary formats for publication output rather than for the editable source file.

Validation Errors on System Schemas (Schema, ProjectSettings, SchemaProperty)

Symptom: Every schema and property in the project shows validation errors such as an invalid identifier, including freshly created schemas.

Charon stores the metadata that describes metadata (the Schema, ProjectSettings, and SchemaProperty system schemas) in the same file as your data. Hand-editing the game data file can accidentally damage them, which breaks validation for everything defined on top.

Warning

Never modify these system documents when editing the game data file manually:

Schema - id 18d4bf318f3c49688087dbed
ProjectSettings - id 55a4f32faca22e191098f3d9
SchemaProperty - id d40d8eb1a23248b69b252eea

Fix: Create a new, empty game data file (e.g. via your engine plugin or charon INIT), open both files in a text editor, and copy the three system schema documents from the fresh file into your damaged one, replacing the broken versions. Make a backup first.

“.NET SDK is not installed” During Setup 

Symptom: The engine plugin fails to set up the game data editor and complains about a missing .NET installation.

Charon is a .NET tool and requires the .NET 8 SDK or later. Download it from dotnet.microsoft.com and verify:

dotnet --list-sdks

After installing the SDK, restart the Unity/Unreal editor. If the plugin still does not detect it, restart the computer so the updated PATH is picked up.

Exported XLSX File Contains an “Errors” Sheet 

Symptom: A DATA EXPORT or localization export produces a spreadsheet that looks empty except for a sheet named Errors.

The export failed and the error details were written into that sheet instead of the console. Open the Errors sheet and read the message - it typically points to the exact document, property, and reason.

Game Data Is Read-Only in the Web Editor 

Symptom: The online editor shows the project as read-only and design changes are rejected, with a message about exceeded limits.

Your workspace has crossed one of its subscription limits. Go to Workspace Settings → Subscriptions and check which limit is exceeded - Projects, Members, or Size. Remove the excess or upgrade the plan; the read-only message disappears once the workspace is back within limits.

Unreal Engine Compile Errors After an Engine Upgrade 

Symptom: After upgrading Unreal Engine, previously generated C++ code or the Charon plugin fails to compile.

New Unreal Engine releases regularly change engine APIs, so support for a new UE version ships in a Charon plugin update. The safe upgrade routine is:

Wait until the new UE version is officially supported (see the release #announcements channel on Discord or https://www.gamedevware.com/whats-new).
Regenerate the C++ source code while still on your current engine version - generated code is backward compatible.
Upgrade the engine and the Charon plugin together, then rebuild.

Import Regenerates IDs of Nested Documents 

Symptom: After importing data (e.g. a localization round-trip), embedded documents receive new identifiers, which shows up as large diffs in version control.

The default import mode replaces embedded collections, recreating their documents. To update existing documents in place:

Pass --mode safeUpdate to DATA IMPORT - it prevents creation and deletion of nested documents.
Or use DATA I18N IMPORT for localization round-trips - it is a specialized import that only touches translated text.

Nothing Helped?

If none of the above solves your problem, reach out directly:

Discord - join the Charon Discord server and ask in the #issues channel. This is usually the fastest way to get help.
GitHub - file a work item at github.com/gamedevware/charon/issues.
Email - write to support@gamedevware.com.

Whichever channel you choose, attach the log files and mention your Charon version, engine (Unity/Unreal/standalone/web), and operating system - it saves a round-trip.