Randomizer troubleshooting

Specific problems and how to fix them. If something here doesn't help, the Discord is the fastest place to ask - the randomizer is the part of Zephyr most likely to need a real human's eyes.

Install / runtime

"Python not detected"

The runtime install never finished, or you uninstalled it manually. Re-open the Archipelago page; if the runtime isn't on disk the Multiplayer view shows a banner with Download & install. Wait for both phases to complete (runtime + dependencies).

If only the dependency phase failed, the banner switches to a Python dependencies not installed state with an Install Python dependencies button that just rebuilds the venv (faster than a full reinstall).

"ModuleNotFoundError: No module named 'X'" on generation

A pip dependency didn't install. Click Install Python dependencies on the runtime banner, or run Refresh schemas in the Custom APWorlds panel to surface the error in the log. If the same module fails twice, copy the error and post it on the Discord - it usually means an APWorld is depending on something not in the standard Archipelago manifest.

Install hangs at "Setting up venv"

On Linux, this usually means missing python3-venv or python3-dev. Install them (sudo apt install python3-venv python3-dev) and retry.

On Windows, antivirus quarantining the venv files. Add Zephyr's data dir to your AV exclusions. The data locations page has the exact path.

Generation

Generation fails immediately

Open the console panel - the error is in there. Common cases:

• Missing YAML field - your YAML doesn't declare a required field. Open it in the configurator; validation errors will be highlighted.
• APWorld import error - a custom APWorld can't be imported. Run Refresh schemas (Custom APWorlds panel) and look at the log - the import error for the broken world is in there.
• logic_failure or fill error - the seed is unsolvable with the options you picked. Loosen logic difficulty, increase progression balancing, or remove restrictive options.

Generation succeeds but produces no patch files

The APWorld doesn't ship patch generation (some PC games are server-only - your client handles patching). The .archipelago file is what matters; you'll connect with the slot name.

Generated .archipelago file is huge

A single seed for a multi-game session can be tens of MB. That's expected. If it's > 100 MB something is wrong - usually a multi-select option set to "everything", with a misconfigured APWorld.

Spoiler log is empty or missing

Some APWorlds opt out of spoiler generation. There's no fix from Zephyr's side; check the world's own readme.

Hosting

Server won't start - "Port already in use"

Another process is on port 38281. Most likely a previous Zephyr server didn't shut down cleanly. Either:

• Kill the orphan: lsof -i :38281 on macOS/Linux, netstat -ano | findstr :38281 on Windows, then kill the PID.
• Change the Port field in the Host block before clicking Start server and tell players the new number.

Players can connect locally but not from the internet

Your router isn't forwarding the port. The easiest fix is a tunnel like Tailscale or Playit.gg, or hosting in Remote mode so archipelago.gg handles the inbound side.

Server crashes randomly during play

Check randomizer/Players/host.yaml (created on first host) for any odd config. Most random crashes trace back to one player's malformed YAML - the server hits the bug on their first item interaction. Open the console, look for tracebacks, identify the player slot, regenerate without them or with a simpler YAML for them.

If the crash is reproducible, file an issue on the Archipelago repo (not Zephyr) - Zephyr is just running upstream code.

Server runs but says "0 players connected"

Players need to actually connect from their game client. Connection isn't automatic - see Joining as a client.

Configurator

Option's dropdown is empty (no items / no choices)

For start inventory: the schema's items list is empty. Run Refresh schemas in the Custom APWorlds panel. If the world is bundled (not a custom one), make sure the runtime is up to date by deleting randomizer/archipelago-runtime/ under your data dir and re-running the install from the Archipelago page.

For a Choice/Select option: the APWorld author didn't define choices. Nothing Zephyr can do; it's an APWorld bug.

Form is greyed out / can't edit

You haven't selected a game from the catalog. Click a game card first. The configurator only renders for an active game.

Saved YAML doesn't match what I see in the form

You're looking at a different game's YAML than the one currently loaded in the configurator. Check the YAML's game: field at the top.

Validation flags an option as invalid but it looks fine

The error tooltip names the validator. Common ones:

• "Must be one of [...]" - your value isn't in the allowed set. Picking from the dropdown will fix it.
• "Conflicts with X" - two options can't both be set the way you have them. The error names the other option.
• "Required" - empty value where one is needed. The form should show this with a red border on the field.

Custom APWorlds

"Not a valid apworld"

The file isn't a proper APWorld zip. It needs:

• .apworld extension
• A zip with one top-level directory containing __init__.py
• A World subclass declared in that __init__.py

If the file works in standalone Archipelago (Generate.py finds the world in custom_worlds/), it should work in Zephyr too. If not, the issue is in the APWorld itself.

Installed but doesn't show in catalog

Run Refresh schemas in the Custom APWorlds panel. If still missing, expand the Last output disclosure under the schemas button and look for the world's name. The error is usually one of:

• Missing dependency the world needs (pip install it into the venv, or wait for the world author to fix).
• Python version mismatch (Zephyr's bundled Python vs the world's required version).
• Syntax error in the world (file an issue with the author).

Performance

Generation is slow

Most games take 10-30 seconds. A few large multi-game seeds take 1-2 minutes. If a single-game generation is taking minutes, the APWorld is doing something expensive - check its docs for "fill complexity" options that can speed things up.

Server is laggy

Check if it's network or CPU. Run top / Task Manager during play. If python.exe is at 100% CPU, the seed might be fighting one player's repeated reconnections - kill that player's connection from the console and ask them to investigate their client.

App is slow to open the randomizer tab

Catalog loading scans every schema file on disk. After a refresh, the first open re-reads them all. Subsequent opens are cached. If it's chronically slow, you might have hundreds of stale custom APWorld schemas - Custom APWorlds panel → uninstall the ones you don't use.

Where to ask

• #randomizer channel on the Zephyr Discord - fastest.
• Zephyr issues on GitHub - for reproducible bugs in Zephyr's randomizer integration.
• Archipelago Discord - for issues that aren't Zephyr-specific (the same error happens in standalone Archipelago).