Server troubleshooting

Server waits and then exits

Confirm the configured <scripts_path>/server/main.js exists and calls vimp.markReady() before script_ready_timeout_secs. Inspect errors from imports and asynchronous initialization before the call.

A module cannot be resolved

Check the deployed package.json module mode and Node's lookup path from server/main.js. Install production dependencies on the target platform.

A native addon fails to load

Use an N-API build compatible with Node 22 and the target OS/architecture. Do not copy a Windows .node binary to Linux or use a raw V8/NAN build.

Remote clients cannot connect

Check host, TCP and UDP firewall rules, NAT forwarding, and whether another process owns the port. 127.0.0.1 accepts only local connections.

Entity creation returns null

The corresponding max_* capacity is exhausted. Find leaked temporary entities, destroy them at feature teardown, or raise the cap after measuring load.

Voice configuration prevents startup

Review the invariants in the voice guide, especially visibility radius and distance relative to shard_size.

Preserve complete server and client logs with timestamps before changing caches or configuration; paired logs are far more useful than the final error alone.