[DOCS] Voice dictation troubleshooting never lists the misleading "Voice connection failed" message fixed in v2.1.200

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/voice-dictation

Section/Topic

The "Troubleshooting" section near the bottom of voice-dictation.md, immediately after the "No audio recording tool found" / "Voice mode requires a microphone" / "Voice mode could not find a working audio recorder in WSL" entries.

Current Documentation

voice-dictation.md documents four troubleshooting messages near the bottom of the page (around lines 169-177). Three of them are titled with the literal message:

No audio recording tool found on Linux: the native audio module could not load and no fallback is installed. Install SoX with the command shown in the error message, for example sudo apt-get install sox. Voice mode requires a microphone, but SoX could not open an audio capture device: SoX is installed, but the host has no audio capture device, for example a headless server or a container. Run Claude Code on a machine with a microphone. As of v2.1.195, Claude Code on Linux reports this message in that situation; earlier versions asked you to install SoX even when it was already installed. Voice mode could not find a working audio recorder in WSL: WSLg routes audio through PulseAudio rather than an ALSA device, so SoX needs its PulseAudio backend installed explicitly. Run sudo apt install sox libsox-fmt-pulse. Installing sox alone pulls in the ALSA backend, which cannot record on WSL because there is no /dev/snd device. No speech detected: audio reached the transcription service but no words were recognized. Speak closer to the microphone, reduce background noise, and confirm your [dictation language](#change-the-dictation-language) matches the language you are speaking.

The earlier "Voice dictation requires Claude Code v2.1.69 or later" section at the top of the page does not address the specific case of a recording that captures no audio.

What's Wrong or Missing?

A. v2.1.200 fixed a misleading "Voice connection failed" message

The v2.1.200 changelog says:

Fixed voice dictation showing a misleading "Voice connection failed" message when a recording captures no audio

Before v2.1.200, pressing the dictation key on a recording that captured zero audio (for example a muted microphone, or pressing Space before the recorder started) reported "Voice connection failed", implying the network or backend service was at fault. After v2.1.200 the message reflects the actual cause.

The troubleshooting list in voice-dictation.md does not include either the old "Voice connection failed" message or the new message that replaces it. Users searching the page for that phrase will not see a matching troubleshooting entry.

B. The "No speech detected" entry overlaps with the new case but is incomplete

The existing "No speech detected" entry says "audio reached the transcription service but no words were recognized." That is the case where the recorder captured something but transcription returned nothing. The v2.1.200 fix is for the upstream case where the recorder captured nothing at all — these are different failure modes that need different messages and different recovery actions.

C. The page does not distinguish "no audio captured" from "audio captured but not recognized"

A muted microphone or a misconfigured capture device will produce zero audio. The current troubleshooting page assumes the audio always reaches the transcription service. After v2.1.200, the docs should distinguish the two failure points so users know which one they are looking at.

Suggested Improvement

Add a new troubleshooting entry next to "No speech detected":

* No audio captured (added in v2.1.200): the recorder captured zero audio during the press. Before v2.1.200 this surfaced as the misleading "Voice connection failed" message. Check that your microphone is unmuted, that the system has granted the terminal microphone permission, and that the input device is not on mute in your OS audio settings. On Linux, the same message appears when the capture device is busy or unavailable.

Update the existing "No speech detected" entry to clarify that it covers only the case where the transcription service received audio but recognized no words, not the new "no audio captured" case.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/voice-dictation | 169-177 | Troubleshooting list |

Total scope: 1 page, one new troubleshooting entry plus a clarification to an existing entry.

The release note for this fix appears in v2.1.200 (July 3, 2026).