Troubleshooting Matrix

Use this page when you want symptom-based diagnosis rather than a generic checklist.

Symptom: client connects, but no one hears anything

Check:

  1. PositioningType match
  2. bind flow completed
  3. entities receive world and position updates
  4. client is not locally muted or deafened
  5. server has not muted or deafened the entity

Symptom: addon connects, but bind never works

Check:

  1. token is correct
  2. the expected entity is created
  3. player used the correct binding key
  4. bind script events are firing

Symptom: GeyserVoice is installed, but Java-side bridge never becomes usable

Check:

  1. McTcp is enabled on VoiceCraft
  2. host, port, and login-token match
  3. direct vs proxy mode is configured intentionally
  4. if auto-start is enabled, the runtime becomes ready within timeout

Symptom: direct Paper mode works after manual reconnect, but not on startup

Check:

  1. config.voicecraft.auto-start
  2. install-directory
  3. ready-timeout-ms
  4. startup ownership of the runtime process

Symptom: proxy mode works on one backend, but breaks on server switch

Check:

  1. proxy is the source of truth
  2. backend nodes are not trying to own the VoiceCraft connection
  3. snapshot forwarding stays intact across switches
  4. world ID namespacing logic remains consistent

Symptom: McWss is unstable

Check:

  1. CommandsPerTick
  2. MaxByteLengthPerCommand
  3. entity churn and packet burst size
  4. whether McHttp would be a better fit

Symptom: VoiceCraft server starts, but transport consumer cannot connect

Check:

  1. host binding
  2. exposed port
  3. firewall
  4. wrong transport type selected
  5. runtime overrides changing the expected values