Skip to main content

Troubleshooting

nexMap is missing​

The runtime bundle has not loaded or has not bootstrapped. Confirm the nexMap4 package groups are enabled, then call nexMap.start() if you installed through the JavaScript bundle. After successful startup the global exposes state, api, and settings.

The map is blank or startup never finishes​

Inspect the startup phase:

nexMap.getStartupState();

A phase of DEGRADED means startup finished with a recoverable problem — most often the remote crowdmap fetch failed. nexMap4 still runs with whatever data it loaded. If it is stuck before READY, the host capabilities (GMCP, eventStream, nexAction, nexusclient) may not all be present yet.

"No nexMap4 route" when traveling​

The destination is unreachable under your current settings. Check, in order:

  1. Travel classes. A needed method may be disabled. Review the Pathing & Travel tab or nexMap.settings.get().disabledTravelClasses.
  2. City Lockouts / excluded rooms. The only route may pass through an excluded room. Review nexMap.settings.get().excludedRoomIds and the City Lockouts tab.
  3. Charted rooms. Both endpoints must exist in the graph. Confirm with nexMap.api.map.getNode(roomId) — a null result means the room is uncharted.

nexMap.api.travel.planRoute(roomId) returns null for the same reasons and is a quick way to test reachability without moving.

The settings dialog does not open​

Use the v4 path:

nexMap.api.system.openSettings();

Older nexMap3 commands and global shortcuts are not the v4 contract.

Settings appear not to save​

The dialog edits a draft — select Save, not Cancel. Then inspect the live document:

nexMap.settings.get();

A Default Zoom change previews live but only persists on Save; cancelling restores the previous zoom.

NPC search fails immediately​

nm npc and nexMap.api.search.denizens require a configured remote denizen client. If it is not configured the search raises "Denizen search requires a configured remote denizen client." Room and area search use the local graph and do not need the remote service.

My room is wrong or the header says "Loading room context"​

nexMap.state.location reports charted: false when the current room is not in the graph. The header and map can only resolve charted rooms. Capture a diagnostic for a bug report:

nm info

Collecting a bug report​

Capture the startup state and a serialized state snapshot:

copy(
JSON.stringify(
{
startup: nexMap.getStartupState(),
state: nexMap.state,
settings: nexMap.settings.get(),
},
null,
2,
),
);

State and settings may include character, room, and landmark information. Review the snapshot before sharing it publicly.

Travel waits or stops with an unknown outcome​

Read nexMap.api.travel.getDiagnostics() for the current or last trip's phase, command, deadlines, charges and unresolved server work. This is a bounded snapshot, with no output recording or game commands. Review room IDs and configured commands before sharing it.

Observation expiry stops autonomous travel but cannot cancel server work. A missing prompt or an uncertain delayed effect may keep later movement waiting. A queued command whose marker never printed is settled by the next trip: it sends one queued path stop, and its marker proves every earlier travel entry left the queue. It reports this with "earlier travel never confirmed". If that stop never runs either, the travel queue itself is not running. Stop and queue clear do not prove an executed effect ended; clear stops affected trips without automatic resume. Balance, looks and timers do not replay a command. Notices identify the action/stage, observation duration and reason so a sourced behavior gap can be reported without guessing.

Speech travel commands can hit the game's speech rate limit when used close together, for example wings followed by a say exit. The exact refusal is recognized for any travel action that is a single say/scream utterance: all three wing types, custom travel commands and room exits such as say I request entry. The attempt waits at least one second from the refusal, then requests a retry within the trip's allowance and response-publication rules. Diagnostics show the remaining retry wait. Rejected submissions do not leave false movement liabilities. Stop notices and passive diagnostics distinguish a stopped trip from genuinely unresolved earlier server work.

Location changed but travel or another package is still waiting​

Every valid Room.Info updates nexMap location immediately. A queued direction, unfinished executing response, delayed effect, tracker cleanup or arrival hook can still prevent travel completion. Check diagnostics for the outstanding liability; a room event does not prove commands settled or room players/items are ready. No extra look/x or early completion notification is added to repair another package's handshake. nexBash remains unchanged by this revision, so its deferred population/completion wait is a separate integration issue. The event reference defines timing.