Universal Modder troubleshooting

Start with the last step that worked. Did the agent launch? Did it find the Universal Modder skills? Can the terminal run um --help? Did the mod build? Did the game load the mod? These are separate checkpoints.

Write down your operating system, agent, installation route, game edition and relevant tool versions. Keep the exact command and error locally. Remove keys, personal paths and account details before sharing a report.

The checks below combine documented setup instructions with explicitly attributed upstream issue reports. A diagnostic suggestion is not a claim that we reproduced your error or verified a fix on your machine.

First confirm the host agent works outside this project. Then compare your installation method with the official installation table. Claude Code uses in-agent slash commands; Codex and Gemini have terminal commands. A skills-only install and a full plugin install are not interchangeable evidence that every component is configured.

If you are working from a clone, start the agent inside the repository so it can discover the local instructions and skills. If you installed a plugin, check its installation state in the agent and try a new session after installation.

Ask the agent to list the relevant skills it can actually access. Do not infer a working integration merely because it can describe Universal Modder from general knowledge. If the command used to install the plugin is itself rejected, check the host agent's version and current plugin interface before changing game files.

Run the check in the same terminal environment you intend to use for modding:

um --help

If the command is missing, revisit the documented independent installation route:

uv tool install git+https://github.com/rehan-remade/universal-modder

Confirm the installation completed successfully, then reopen the terminal and check again. If it still fails, inspect the tool environment and executable path rather than repeatedly installing copies under different Python environments.

Windows and WSL have separate environments. A tool installed in one is not automatically visible in the other. Record where uv, Python and the agent run. Once you can display CLI help, move on to checking the integration; do not start troubleshooting game compatibility while the command itself is unavailable.

Upstream issue #152 reports a Windows UnicodeEncodeError involving the cp1252 encoding while running a knowledge-base search. The reporter describes enabling Python UTF-8 mode as a workaround:

$env:PYTHONUTF8 = "1"
um kb search aoe

This syntax is for PowerShell. The environment setting applies to processes started from that session; do not paste it unchanged into another shell and expect the same behavior.

Treat this as a reported workaround for the described encoding problem, not as a universal repair command. Compare your error with the issue, inspect the latest discussion, and retry only the failing read operation. A missing package, network failure or game crash is a different problem.

First identify the chosen route. The official project supports fal-based generation and a local ComfyUI path for images. Those paths have different prerequisites.

For fal, check that the required key is available to the process running the tool, that your account can use the selected model, and that you understand the current price before retrying a job. Do not paste the key into a public issue. Avoid submitting the same paid task repeatedly while its state is uncertain.

For local ComfyUI, check that your server runs and that the required workflow and models are available. “No fal key needed” does not mean “no setup needed.” Inspect the relevant help before a generation attempt:

um comfy --help
um fal --help

If assets are not needed for the first code test, postpone this layer and establish the mod's basic behavior first. The costs guide separates these dependencies.

Check the simple boundary first: did you launch the correct game edition through the expected loader, and is the mod enabled? Compare the build output location with the example's installation instructions. A correctly built file in the wrong folder has not been tested in game.

Then compare versions. Record the game build, mod loader and any renderer or framework involved. Disable unrelated mods for a controlled test only if you can preserve and restore your current setup. Use a spare save and change one factor at a time.

For complex examples, follow each component's startup sequence. A two-game mashup has more failure points than a single loader mod. Issue #180, for example, reports invisible Minecraft blocks and HUD elements in the GTA V example. It is evidence of a reported symptom, not a verified generic fix. Read the current thread rather than substituting an unrelated graphics tweak.

Stop adding new changes once the working state is unclear. Close the game, keep the failing mod and logs in a separate folder, and follow the rollback plan you made before editing. If you are using the project's backup tools, read the installed version's help and verify the snapshot and destination before restoring.

Confirm the clean game or last working mod launches again. That result gives you a baseline for another attempt. If it does not, record that separately instead of assuming the new mod is the only cause.

A useful upstream issue includes the installation method, agent and operating system, game and loader versions, the exact failing step, the expected result, and the shortest reproduction you can provide. Include the relevant error text after removing private information.

Say what you have already checked and what remains untested. Do not post full game files, saves containing personal information, keys or decompiled dumps. For a mistake in this guide, contact [email protected] with the page and the correction source.

Return to installation for a clean setup checklist, or the first-mod workflow for a smaller controlled test.