Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
This document provides guidance for diagnosing and resolving common issues with the Voice ElevenLabs plugin. It covers problems related to initial setup, configuration, command execution, and automated voice notifications (hooks).
The primary sources of issues are typically incorrect environment variable setup, missing dependencies, or problems with the ElevenLabs API connection. Following the steps in this guide should help isolate and fix most problems.
Initial Setup and Configuration
Correct setup is critical for the plugin to function. Issues in this stage will prevent all voice features from working.
Key Dependencies and Configuration Points
| Item | Requirement | Verification | Common Issues |
|---|---|---|---|
| ElevenLabs API Key | ELEVENLABS_API_KEY environment variable must be set. | Run echo $ELEVENLABS_API_KEY in your terminal. | Key is missing, incorrect, or not exported correctly in shell profile (~/.zshrc). |
| Voice Notifications CLI | claude-voice-notifications must be installed globally via npm. | Run which claude-voice-notifications. | Command not found; npm installation failed or is not in the system's PATH. |
| Voice ID | ELEVENLABS_VOICE_ID environment variable (optional). | Run echo $ELEVENLABS_VOICE_ID. | If set, the ID might be invalid. If unset, it uses the default. |
Sources: README.md:16-27, commands/voice-config.md:11, commands/voices.md:18-22
Setup Verification Flow
This diagram illustrates the steps to verify your setup. A failure at any step is a potential point of error.
Sources: README.md:16-27, commands/voice-config.md:21
Using /voice-config to Diagnose
The /voice-config command is the primary tool for debugging configuration issues.
/voice-config show: Displays whether the API key is detected and shows the currently configured voice ID. This should be your first step./voice-config test: Attempts to play a test message. If this fails, it confirms a problem with your API key, network connection, or theclaude-voice-notificationstool.
Sources: commands/voice-config.md:10-24
Command Execution Issues
If configuration is correct but specific commands fail, the problem may lie in the command's execution logic.
/speak Command Failure
The /speak command is a good indicator of core functionality. If it fails, no other voice features will work.
Execution Flow
The diagram below shows the two potential execution paths for the /speak command. The primary method uses claude-voice-notifications, but a direct API call with curl is also documented as an alternative, which can be useful for debugging.
This diagram illustrates the two methods documented for text-to-speech generation.
Sources: commands/speak.md:21-30
Troubleshooting Steps:
- Check for Typos: Ensure emotion tags like
[excited]are spelled correctly and enclosed in brackets. - Test
claude-voice-notificationsDirectly: Open a terminal and run:
If this fails, the issue is with the notification tool or your environment, not the plugin itself.echo '{"hook_event_name": "Stop", "message": "This is a direct test"}' | claude-voice-notifications - Test with
curl: Use thecurlcommand provided in the documentation to bypass the notification tool and test your API key and network connection directly with ElevenLabs.
If this works but the command in Claude Code does not, the problem is likely with how the plugin invokes the tool.curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb" \ -H "xi-api-key: $ELEVENLABS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"text": "Direct API test", "model_id": "eleven_v3_alpha"}' \ --output /tmp/test.mp3 && afplay /tmp/test.mp3
Sources: commands/speak.md:11-30
Automated Hook Failures
The plugin uses hooks to provide voice notifications for events like Stop, SubagentStop, and Notification. If these are not working, the issue is likely in the hook configuration or the scripts they execute.
Hook Registration
The hooks/hooks.json file defines which events trigger which scripts.
| Event | Script/Command | Description |
|---|---|---|
Stop | ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/stop-voice.sh | Announces "[project]: done" when Claude finishes. |
SubagentStop | ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/subagent-voice.sh | Announces "[project]: [task]" when a subagent completes. |
Notification | claude-voice-notifications | Announces when Claude needs permission or input. |
Sources: hooks/hooks.json:2-17
Hook Execution Flow
This diagram shows how an event like SubagentStop triggers a voice notification.
This flowchart details the process from event trigger to audio playback for a subagent hook.
Sources: hooks/hooks.json:8-12, hooks/scripts/subagent-voice.sh
Troubleshooting Steps:
- Check Script Permissions: Ensure the shell scripts in
hooks/scripts/are executable (chmod +x *.sh). - Check for
jq: The hook scripts depend on thejqcommand-line JSON processor. Ensure it is installed and in yourPATH. - Examine Script Logic: The scripts
stop-voice.shandsubagent-voice.shattempt to parse the project name from the current working directory (cwd). If you are not in a project directory, the message may be generic (e.g., "Claude done" or "Task completed"). - Manual Script Test: You can simulate a hook event to test a script directly in your terminal. For example, to test
stop-voice.sh:
This should trigger the voice notification "my-project: done". If it doesn't, there is an issue with the script or its dependencies.echo '{"cwd": "/Users/test/my-project"}' | ~/.claude/plugins/voice-elevenlabs/hooks/scripts/stop-voice.sh
Sources: hooks/scripts/stop-voice.sh:5-18, hooks/scripts/subagent-voice.sh:5-32