> ## Documentation Index
> Fetch the complete documentation index at: https://docs.augent.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them.

## Quick diagnostic

Run these three commands to diagnose most issues:

```bash theme={null}
# 1. Is Augent installed?
augent --version

# 2. Is the MCP server working?
augent-mcp <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 3. Is FFmpeg available?
ffmpeg -version
```

If step 1 fails, see [command not found](#command-not-found-after-install). If step 2 fails, see [MCP not connecting](#mcp-server-not-connecting). If step 3 fails, see [FFmpeg missing](#transcription-fails).

***

## 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:

```bash theme={null}
source ~/.zshrc    # macOS
source ~/.bashrc   # Linux
```

If it still fails, check that the binary exists:

```bash theme={null}
ls ~/.local/bin/augent
```

If it doesn't exist, reinstall:

```bash theme={null}
curl -fsSL https://augent.app/install.sh | bash
```

### 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:

```bash theme={null}
which python3
python3 -c "import augent; print(augent.__file__)"
```

If they point to different Python installations, reinstall to the correct one:

```bash theme={null}
python3 -m pip install augent[all]
```

***

## 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:

```bash theme={null}
claude mcp list
```

If Augent isn't listed, register it:

```bash theme={null}
claude mcp add augent -s user -- augent-mcp
```

Then restart Claude Code.

If it's listed but disconnected, test the server directly:

```bash theme={null}
augent-mcp <<< '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
```

You should see a JSON response with `protocolVersion`. If you get an error, check the [install issues](#install-issues) section.

***

## Transcription issues

### Transcription fails

**Symptom:** Error mentioning FFmpeg, or transcription hangs/crashes.

**Fix:** Augent requires FFmpeg for audio processing:

```bash theme={null}
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg
```

### 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:

```bash theme={null}
yt-dlp --version
brew upgrade yt-dlp    # macOS
pip install -U yt-dlp  # or via pip
```

Some sites require authentication or have rate limits. If a specific URL fails, try it directly:

```bash theme={null}
yt-dlp --print filename "URL"
```

### aria2c not found (slower downloads)

**Symptom:** Downloads work but are slow.

**Fix:** aria2c enables 16 parallel connections. Install it:

```bash theme={null}
# macOS
brew install aria2

# Ubuntu/Debian
sudo apt install aria2
```

***

## Feature-specific issues

### Speaker identification fails

**Symptom:** `identify_speakers` returns an import error.

**Fix:** Speaker diarization requires pyannote-audio and pre-downloaded models:

```bash theme={null}
pip install augent[speakers]
```

The models (\~29MB) should have been downloaded by the installer. If they're missing, reinstall:

```bash theme={null}
curl -fsSL https://augent.app/install.sh | bash
```

### Text-to-speech fails

**Symptom:** `text_to_speech` returns an import error or fails silently.

**Fix:**

```bash theme={null}
pip install augent[tts]
brew install espeak-ng    # macOS — required by Kokoro
```

### Source separation fails

**Symptom:** `separate_audio` returns an import error.

**Fix:**

```bash theme={null}
pip install augent[separator]
```

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:**

```bash theme={null}
pip install augent[semantic]
```

This installs sentence-transformers (\~80MB model downloaded on first use).

***

## Still stuck?

1. Check [GitHub Issues](https://github.com/AugentDevs/Augent/issues) for known problems
2. Ask in [Discord](https://discord.com/invite/DNmaZtaE7b)
3. Enterprise support: [support@augent.app](mailto:support@augent.app)