Diagnose a failed join

Read logs/host.log and logs/client.log, beside the install. The console shows a summary; the files carry the detail.

Read this before anything else

A player who is refused also logs that it entered the session, so “it connected” proves nothing on its own. What tells the two apart is whether the player is still there a moment later.

And when a player is refused, the reason is in their log. The host is never told it.

The player is refused, and something is named

this session runs content this install does not have: acme:doors@0.3.1. Install it to join

Cause: your session runs a mod, at a version, that the player does not have. The list names everything missing at once, and a mod they hold at the wrong version says so: acme:doors@0.3.1 (installed here at 0.3.0).

Fix: they install what is named, at that version, and rejoin. There is no partial join on purpose — the parts they lack would silently be missing from the world around them, which is worse than being turned away. See Enabled mods for why the set is the host’s to decide.

The player joins and sees a black screen

Cause: almost always the map. The host is on a map that player does not have, so their world never loads. Their log says which:

this session is on the map acme:citadel, which is not installed here

Fix: give them the mod carrying that map. Note this reproduces reliably only on the first join into a fresh process, so a second attempt “working” does not mean it is fixed.

A mod does not run, and the session is otherwise fine

Cause: its code never entered the session, and by far the most common reason is that the component was never built. The manifest resolves, the mod is enabled, the gamemode is even designated — and the session then runs without a line of the code the author is sitting in front of. The host log names it and prints the exact command that fixes it:

mod acme:doors has a server realm that is not built: no component at /home/alice/.ironlark/assets/workshop/acme/doors/doors_server.wasm. Build it with: cargo build --release --target wasm32-wasip2 --manifest-path /home/alice/.ironlark/assets/workshop/acme/doors/Cargo.toml

Fix: run that command. It is printed for whichever half is missing — a mod with no client or server source at all is not this case, and is noted at INFO rather than as an error.

A mod that was built but failed to load also takes itself out of the session and nothing else with it — joins, spawning and the tick all carry on, so the only symptom is the one mod’s absence. Find it near session start:

grep 'is out for this session' logs/host.log

The line names the mod, the half and the reason:

server-mod acme:doors is out for this session: <the reason>

A mod that loaded and then failed while running is different: it is retired and given a fresh instance, and only after failing repeatedly — or after growing past the memory ceiling, which a fresh instance would hit again — is it quarantined for the rest of the session. The log says which happened, as was retired, reloading, or quarantined for the session.

The session refuses to start and names two gamemodes

several installed mods fill the gamemode role and none was selected; name one of these in [session] gamemode: acme:deathmatch, ironlark:freeroam

Cause: two installed mods can hold the gamemode role and nothing chose one. The host will not guess which rules you meant.

Fix: working as intended — name one. Either --gamemode <id> for this run, or [session] gamemode in config/server.toml to settle it. See Configuration.

The player is present, then gone a moment later

Cause: one of the refusals above. The host log will not tell you which.

Fix: get their logs/client.log. The reason is the first error in it after the join attempt.

Nothing connects at all, for anyone

Cause: connection setup, not content. Both peers must be able to reach the signalling and core servers, and both must be on the same game version.

Fix: confirm both players can log in at all — a failure to authenticate looks like a failure to connect. There is no port to forward, so do not go looking for one; see Connectivity for what actually carries the traffic.

If it worked yesterday and does not today, check you are on a current build before debugging anything: the servers a build talks to are compiled into it, so a moved domain breaks an older build in exactly this way. See when it breaks.

One player cannot connect, and everyone else can

Cause: their network, most likely. When no direct path exists, traffic goes through a relay, and some networks cannot reach the one we hand out. Relay traffic is UDP, so a network that blocks it has no fallback.

Fix: this is not something you can configure from your side. Send us their logs/client.log in Discord — we can put them on a different relay.