Skip to main content

​
Quick diagnostic

Run these three commands to diagnose most issues:
If step 1 fails, see command not found. If step 2 fails, see MCP not connecting. If step 3 fails, see FFmpeg missing.

​
Install issues

​
Command not found after install

Symptom: augent: command not found or augent-mcp: command not found Fix: The installer adds ~/.local/bin to your PATH via your shell rc file. Either restart your terminal or run:
If it still fails, check that the binary exists:
If it doesn’t exist, reinstall:

​
pip installed to wrong Python

Symptom: augent runs but imports fail, or ModuleNotFoundError for faster_whisper, sentence_transformers, etc. Fix: This happens when python3 resolves to a different version than the one pip installed to. Check which Python is being used:
If they point to different Python installations, reinstall to the correct one:

​
MCP issues

​
MCP server not connecting

Symptom: /mcp in Claude Code doesn’t show Augent, or shows it as disconnected. Fix: Check the MCP registration:
If Augent isn’t listed, register it:
Then restart Claude Code. If it’s listed but disconnected, test the server directly:
You should see a JSON response with protocolVersion. If you get an error, check the install issues section.

​
Transcription issues

​
Transcription fails

Symptom: Error mentioning FFmpeg, or transcription hangs/crashes. Fix: Augent requires FFmpeg for audio processing:

​
Model download slow on first run

Symptom: First transcription takes a long time before producing output. This is normal. The Whisper model downloads on first use (~75MB for tiny, larger for other sizes). Subsequent runs use the cached model. The sentence-transformer model (~80MB) also downloads on first semantic search.

​
Download issues

​
Download fails or hangs

Symptom: download_audio returns an error or hangs indefinitely. Fix: Check that yt-dlp is installed and up to date:
Some sites require authentication or have rate limits. If a specific URL fails, try it directly:

​
aria2c not found (slower downloads)

Symptom: Downloads work but are slow. Fix: aria2c enables 16 parallel connections. Install it:

​
Feature-specific issues

​
Speaker identification fails

Symptom: identify_speakers returns an import error. Fix: Speaker diarization requires pyannote-audio and pre-downloaded models:
The models (~29MB) should have been downloaded by the installer. If they’re missing, reinstall:

​
Text-to-speech fails

Symptom: text_to_speech returns an import error or fails silently. Fix:

​
Source separation fails

Symptom: separate_audio returns an import error. Fix:
This installs Demucs and PyTorch. It’s a large download (~2GB for PyTorch).

​
Deep search / chapters not working

Symptom: deep_search or chapters returns an import error. Fix:
This installs sentence-transformers (~80MB model downloaded on first use).

​
Still stuck?

  1. Check GitHub Issues for known problems
  2. Ask in Discord
  3. Enterprise support: support@augent.app