# Troubleshooting & FAQ

Common issues, diagnostics, and answers to frequently asked questions about LibreFang.

## Table of Contents

- [Quick Diagnostics](#quick-diagnostics)
- [Installation Issues](#installation-issues)
- [Configuration Issues](#configuration-issues)
- [LLM Provider Issues](#llm-provider-issues)
- [Channel Issues](#channel-issues)
- [Agent Issues](#agent-issues)
- [Plugin Issues](#plugin-issues)
- [API Issues](#api-issues)
- [Desktop App Issues](#desktop-app-issues)
- [Performance](#performance)
- [FAQ](#faq)

---

## Quick Diagnostics

Run the built-in diagnostic tool:

```bash
librefang doctor
```

This checks:
- Configuration file exists and is valid TOML
- API keys are set in environment
- Database is accessible
- Daemon status (running or not)
- Port availability
- Tool dependencies (Python, signal-cli, etc.)

#### Audit checks

`librefang doctor` additionally runs a registered set of `AuditCheck`s — opinionated lints for the misconfigurations that have caused the most issues in practice. Each check returns one of `pass` / `warn` / `fail`; `--json` emits a machine-readable bundle.

| Check | What it asserts |
|---|---|
| `VaultKeyCheck` | `LIBREFANG_VAULT_KEY`, when set, base64-decodes to **exactly 32 bytes**. The classic 32-ASCII-character mistake produces a 32-character string that doesn't decode to a 32-byte key. |
| `ApiListenAddrCheck` | `api_listen` is reachable from the configured `LIBREFANG_PORT`, and a non-loopback bind has `api_key` set so the daemon isn't accidentally exposed unauthenticated. |
| `ConfigTomlSchemaCheck` | `config.toml` parses cleanly against the live `KernelConfig` schema; unknown keys, type mismatches, and ranges-out-of-bounds are flagged before the daemon starts. |

Add new checks by implementing the `AuditCheck` trait in `crates/librefang-cli/src/doctor.rs` and registering them in `registered_checks()`.

#### Foreground daemon log files

`librefang start --foreground` (the mode `just dev` and many supervisors use) now **tees stdout to both the terminal and a daily rotating file** at `~/.librefang/logs/daemon-YYYY-MM-DD.log`. Same-day restarts append to the existing file; a new day spawns a fresh one. Files older than 7 days are pruned on the next daemon start.

Previously the foreground path wrote only to the terminal, so logs were lost the moment the supervisor scrolled them off-screen.

```bash
tail -f ~/.librefang/logs/daemon-$(date +%F).log
```

### Check Daemon Status

```bash
librefang status
```

### Check Health via API

```bash
curl http://127.0.0.1:4545/api/health
curl http://127.0.0.1:4545/api/health/detail  # Requires auth
```

### View Logs

LibreFang uses `tracing` for structured logging. Set the log level via environment:

```bash
RUST_LOG=info librefang start          # Default
RUST_LOG=debug librefang start         # Verbose
RUST_LOG=librefang=debug librefang start  # Only LibreFang debug, deps at info
```

---

## Installation Issues

### `cargo install` fails with compilation errors

**Cause**: Rust toolchain too old or missing system dependencies.

**Fix**:
```bash
rustup update stable
rustup default stable
rustc --version  # Need 1.75+
```

On Linux, you may also need:
```bash
# Debian/Ubuntu
sudo apt install pkg-config libssl-dev libsqlite3-dev

# Fedora
sudo dnf install openssl-devel sqlite-devel
```

### `librefang` command not found after install

**Fix**: Ensure `~/.cargo/bin` is in your PATH:
```bash
export PATH="$HOME/.cargo/bin:$PATH"
# Add to ~/.bashrc or ~/.zshrc to persist
```

### Docker container won't start

**Common causes**:
- No API key provided: `docker run -e GROQ_API_KEY=... ghcr.io/librefang/librefang`
- Port already in use: change the port mapping `-p 3001:4545`
- Permission denied on volume mount: check directory permissions

---

## Configuration Issues

### "Config file not found"

**Fix**: Run `librefang init` to create the default config:
```bash
librefang init
```

This creates `~/.librefang/config.toml` with sensible defaults.

### "Missing API key" warnings on start

**Cause**: No LLM provider API key found in environment.

**Fix**: Set at least one provider key:
```bash
export GROQ_API_KEY="gsk_..."     # Groq (free tier available)
# OR
export ANTHROPIC_API_KEY="sk-ant-..."
# OR
export OPENAI_API_KEY="sk-..."
```

Add to your shell profile to persist across sessions.

### Config validation errors

Run validation manually:
```bash
librefang config show
```

Common issues:
- Malformed TOML syntax (use a TOML validator)
- Invalid port numbers (must be 1-65535)
- Missing required fields in channel configs

### "Port already in use"

**Fix**: Change the port in config or kill the existing process:
```bash
# Change API port
# In config.toml:
# [api]
# listen_addr = "127.0.0.1:3001"

# Or find and kill the process using the port
# Linux/macOS:
lsof -i :4545
# Windows:
netstat -aon | findstr :4545
```

---

## LLM Provider Issues

### "Authentication failed" / 401 errors

**Causes**:
- API key not set or incorrect
- API key expired or revoked
- Wrong env var name

**Fix**: Verify your key:
```bash
# Check if the env var is set
echo $GROQ_API_KEY

# Test the provider
curl http://127.0.0.1:4545/api/providers/groq/test -X POST
```

### "Rate limited" / 429 errors

**Cause**: Too many requests to the LLM provider.

**Fix**:
- The driver automatically retries with exponential backoff
- Reduce `max_llm_tokens_per_hour` in agent capabilities
- Switch to a provider with higher rate limits
- Use multiple providers with model routing

### Slow responses

**Possible causes**:
- Provider API latency (try Groq for fast inference)
- Large context window (use `/compact` to shrink session)
- Complex tool chains (check iteration count in response)

**Fix**: Use per-agent model overrides to use faster models for simple agents:
```toml
[model]
provider = "groq"
model = "llama-3.1-8b-instant"  # Fast, small model
```

### "Model not found"

**Fix**: Check available models:
```bash
curl http://127.0.0.1:4545/api/models
```

Or use an alias:
```toml
[model]
model = "llama"  # Alias for llama-3.3-70b-versatile
```

See the full alias list:
```bash
curl http://127.0.0.1:4545/api/models/aliases
```

### Ollama / local models not connecting

**Fix**: Ensure the local server is running:
```bash
# Ollama
ollama serve  # Default: http://localhost:11434

# vLLM
python -m vllm.entrypoints.openai.api_server --model ...

# LM Studio
# Start from the LM Studio UI, enable API server
```

---

## Channel Issues

### Telegram bot not responding

**Checklist**:
1. Bot token is correct: `echo $TELEGRAM_BOT_TOKEN`
2. Bot has been started (send `/start` in Telegram)
3. If `allowed_users` is set, your Telegram user ID or username is in the list (accepts `"123456789"`, `"alice"`, or `"@alice"`)
4. Check logs for "Telegram adapter" messages

### Discord bot offline

**Checklist**:
1. Bot token is correct
2. **Message Content Intent** is enabled in Discord Developer Portal
3. Bot has been invited to the server with correct permissions
4. Check Gateway connection in logs

### Slack bot not receiving messages

**Checklist**:
1. Both `SLACK_BOT_TOKEN` (xoxb-) and `SLACK_APP_TOKEN` (xapp-) are set
2. Socket Mode is enabled in the Slack app settings
3. Bot has been added to the channels it should monitor
4. Required scopes: `chat:write`, `app_mentions:read`, `im:history`, `im:read`, `im:write`

### Webhook-based channels (WhatsApp, LINE, etc.)

**Checklist**:
1. Your server is publicly accessible (or use a tunnel like ngrok)
2. Webhook URL is correctly configured in the platform dashboard
3. Webhook port is open and not blocked by firewall
4. Verify token matches between config and platform dashboard

### "Channel adapter failed to start"

**Common causes**:
- Missing or invalid token
- Port already in use (for webhook-based channels)
- Network connectivity issues

Check logs for the specific error:
```bash
RUST_LOG=librefang_channels=debug librefang start
```

---

## Agent Issues

### Agent stuck in a loop

**Cause**: The agent is repeatedly calling the same tool with the same parameters.

**Automatic protection**: LibreFang has a built-in loop guard:
- **Warn** at 3 identical tool calls
- **Block** at 5 identical tool calls
- **Circuit breaker** at 30 total blocked calls (stops the agent)

**Manual fix**: Cancel the agent's current run:
```bash
curl -X POST http://127.0.0.1:4545/api/agents/{id}/stop
```

Or via chat command: `/stop`

### Agent running out of context

**Cause**: Conversation history is too long for the model's context window.

**Fix**: Compact the session:
```bash
curl -X POST http://127.0.0.1:4545/api/agents/{id}/session/compact
```

Or via chat command: `/compact`

Auto-compaction is enabled by default when the session reaches the threshold (configurable at runtime; not exposed in `config.toml`).

### Agent not using tools

**Cause**: Tools not granted in the agent's capabilities.

**Fix**: Check the agent's manifest:
```toml
[capabilities]
tools = ["file_read", "web_fetch", "shell_exec"]  # Must list each tool
# OR
# tools = ["*"]  # Grant all tools (use with caution)
```

### "Permission denied" errors in agent responses

**Cause**: The agent is trying to use a tool or access a resource not in its capabilities.

**Fix**: Add the required capability to the agent manifest. Common ones:
- `tools = [...]` for tool access
- `network = ["*"]` for network access
- `memory_write = ["self.*"]` for memory writes
- `shell = ["*"]` for shell commands (use with caution)

### Agent spawning fails

**Check**:
1. TOML manifest is valid: `librefang agent spawn --dry-run manifest.toml`
2. LLM provider is configured and has a valid key
3. Model specified in manifest exists in the catalog

---

## Plugin Issues

### Context engine plugin silently does nothing

**Cause**: usually the plugin's declared runtime isn't installed on this host. The hook fails with `LauncherNotFound`, LibreFang logs a warning, and falls back to the default context engine — so nothing crashes, nothing visible changes, and memories just never come back.

**Diagnose**: call the doctor endpoint.

```bash
curl http://127.0.0.1:4545/api/plugins/doctor
```

Look for:
- `runtimes[].available: false` → the runtime's launcher (e.g. `go`, `deno`, `ruby`) isn't on PATH. Install it per the `install_hint` field.
- `plugins[].runtime_available: false` → the plugin's declared runtime is missing.
- `plugins[].hooks_valid: false` → a hook script declared in `plugin.toml` doesn't exist on disk.

In Docker, most runtimes aren't pre-installed — extend the image. See [Configuration → Plugins](./configuration#context_engine) for copy-paste `RUN` snippets.

### Hook script hangs / times out

**Cause**: hooks have a 30-second wall-clock timeout. Common culprits: blocking network calls, unclosed stdin reads, accidentally waiting on `input()` or `readline` with no data.

**Check**:
1. Test the hook manually: `echo '{"type":"ingest","agent_id":"t","message":"hi","peer_id":null}' | python3 hooks/ingest.py` — it should print one line and exit.
2. If it hangs, the script is reading more than just stdin.
3. Look at LibreFang logs for `Timeout` entries naming your hook.

### Hook runs but memories don't show up

**Cause**: output isn't valid JSON, or the last line of stdout isn't the JSON response.

LibreFang scans stdout from bottom to top and uses the first JSON-parseable line. Debug logs printed *before* the JSON are fine; logs printed *after* are fine; but if the last line is something like `done.` or a traceback, the response is lost.

**Check**: pipe stdout through `tail -n1` locally and confirm it's a valid `{"type": "ingest_result", ...}` object.

### Plugin installed but not loaded

**Cause**: `plugin` or `hooks` field not set in `config.toml`.

```toml
[context_engine]
plugin = "your-plugin-name"   # resolves to ~/.librefang/plugins/your-plugin-name/
```

Or configure hooks manually without a plugin dir:

```toml
[context_engine.hooks]
ingest = "~/.librefang/scripts/my_ingest.py"
runtime = "python"
```

Restart LibreFang after editing config.

---

## API Issues

### 401 Unauthorized

**Cause**: API key required but not provided.

**Fix**: Include the Bearer token:
```bash
curl -H "Authorization: Bearer your-api-key" http://127.0.0.1:4545/api/agents
```

### 429 Too Many Requests

**Cause**: GCRA rate limiter triggered.

**Fix**: Wait for the `Retry-After` period, or increase rate limits in config:
```toml
[api]
rate_limit_per_second = 20  # Increase if needed
```

### CORS errors from browser

**Cause**: Trying to access API from a different origin.

**Fix**: Add your origin to CORS config:
```toml
[api]
cors_origins = ["http://localhost:5173", "https://your-app.com"]
```

### WebSocket disconnects

**Possible causes**:
- Idle timeout (send periodic pings)
- Network interruption (reconnect automatically)
- Agent crashed (check logs)

**Client-side fix**: Implement reconnection logic with exponential backoff.

### OpenAI-compatible API not working with my tool

**Checklist**:
1. Use `POST /v1/chat/completions` (not `/api/agents/{id}/message`)
2. Set the model to `librefang:agent-name` (e.g., `librefang:coder`)
3. Streaming: set `"stream": true` for SSE responses
4. Images: use `image_url` with `data:image/png;base64,...` format

---

## Desktop App Issues

### App won't start

**Checklist**:
1. Only one instance can run at a time (single-instance enforcement)
2. Check if the daemon is already running on the same ports
3. Try deleting `~/.librefang/daemon.json` and restarting

### White/blank screen in app

**Cause**: The embedded API server hasn't started yet.

**Fix**: Wait a few seconds. If persistent, check logs for server startup errors.

### System tray icon missing

**Platform-specific**:
- **Linux**: Requires a system tray (e.g., `libappindicator` on GNOME)
- **macOS**: Should work out of the box
- **Windows**: Check notification area settings, may need to show hidden icons

---

## Performance

### High memory usage

**Tips**:
- Reduce the number of concurrent agents
- Use session compaction for long-running agents
- Use smaller models (Llama 8B instead of 70B for simple tasks)
- Clear old sessions: `DELETE /api/sessions/{id}`

### Slow startup

**Normal startup**: `&lt;200ms` for the kernel, `~1-2s` with channel adapters.

If slower:
- Check database size (`~/.librefang/data/librefang.db`)
- Reduce the number of enabled channels
- Check network connectivity (MCP server connections happen at boot)

### High CPU usage

**Possible causes**:
- WASM sandbox execution (fuel-limited, should self-terminate)
- Multiple agents running simultaneously
- Channel adapters reconnecting (exponential backoff)

---

## FAQ

### How do I switch the default LLM provider?

Edit `~/.librefang/config.toml`:
```toml
[default_model]
provider = "groq"
model = "llama-3.3-70b-versatile"
api_key_env = "GROQ_API_KEY"
```

### Can I use multiple providers at the same time?

Yes. Each agent can use a different provider via its manifest `[model]` section. The kernel creates a dedicated driver per unique provider configuration.

### How do I add a new channel?

1. Add the channel config to `~/.librefang/config.toml` under `[channels]`
2. Set the required environment variables (tokens, secrets)
3. Restart the daemon

### How do I update LibreFang?

```bash
# From source
cd librefang && git pull && cargo install --path crates/librefang-cli

# Docker
docker pull ghcr.io/librefang/librefang:latest
```

### Can agents talk to each other?

Yes. Agents can use the `agent_send`, `agent_spawn`, `agent_find`, and `agent_list` tools to communicate. The orchestrator template is specifically designed for multi-agent delegation.

### Is my data sent to the cloud?

Only LLM API calls go to the provider's servers. All agent data, memory, sessions, and configuration are stored locally in SQLite (`~/.librefang/data/librefang.db`). The OFP wire protocol authenticates P2P traffic with two layers: a `shared_secret` HMAC admission gate plus per-node Ed25519 identity with TOFU pinning (`peer_keypair.json` + `trusted_peers.json` in the data dir). See `/api/network/status` for the local fingerprint.

### How do I back up my data?

Back up these files:
- `~/.librefang/config.toml` (configuration)
- `~/.librefang/data/librefang.db` (all agent data, memory, sessions)
- `~/.librefang/skills/` (installed skills)

### How do I reset everything?

```bash
rm -rf ~/.librefang
librefang init  # Start fresh
```

### Can I run LibreFang without an internet connection?

Yes, if you use a local LLM provider:
- **Ollama**: `ollama serve` + `ollama pull llama3.2`
- **vLLM**: Self-hosted model server
- **LM Studio**: GUI-based local model runner

Set the provider in config:
```toml
[default_model]
provider = "ollama"
model = "llama3.2"
```

### What's the difference between LibreFang and OpenClaw?

| Aspect | LibreFang | OpenClaw |
|--------|----------|----------|
| Language | Rust | Python |
| Channels | 40 | 38 |
| Skills | 60 | 57 |
| Providers | 20 | 3 |
| Security | 16 systems | Config-based |
| Binary size | ~30 MB | ~200 MB |
| Startup | `&lt;200 ms` | `~3 s` |

LibreFang can import OpenFang configs: `librefang migrate --from openfang`

LibreFang can also import OpenClaw configs: `librefang migrate --from openclaw`

### How do I report a bug or request a feature?

- Bugs: Open an issue on GitHub
- Security: See [SECURITY.md](../SECURITY.md) for responsible disclosure
- Features: Open a GitHub discussion or PR

### What are the system requirements?

| Resource | Minimum | Recommended |
|----------|---------|-------------|
| RAM | 128 MB | 512 MB |
| Disk | 50 MB (binary) | 500 MB (with data) |
| CPU | Any x86_64/ARM64 | 2+ cores |
| OS | Linux, macOS, Windows | Any |
| Rust | 1.75+ (build only) | Latest stable |

### How do I enable debug logging for a specific crate?

```bash
RUST_LOG=librefang_runtime=debug,librefang_channels=info librefang start
```

### Can I use LibreFang as a library?

Yes. Each crate is independently usable:
```toml
[dependencies]
librefang-runtime = { path = "crates/librefang-runtime" }
librefang-memory = { path = "crates/librefang-memory" }
```

The `librefang-kernel` crate assembles everything, but you can use individual crates for custom integrations.





