Troubleshooting

Start with Doctor whenever Bestie behaves weirdly. Guessing is fun until you spend 40 minutes fighting a missing env var like a raccoon in a server room.

bestie doctor

Setup issues

bestie command not found

Check whether the installer linked Bestie into your user-local bin directory:

ls ~/.local/bin/bestie

If it exists, make sure ~/.local/bin is on your PATH.

Missing config

Run onboarding again:

bestie onboard

If you are setting up offline or the provider is temporarily unavailable:

bestie onboard --skip-provider-test

Doctor reports unsafe .env permissions

Doctor can repair safe local permissions:

bestie doctor --fix

--fix does not overwrite config, prompts, or secrets.

Provider issues

Provider request timed out

The provider endpoint was contacted but did not return before the timeout.

Try:

• Run the request again.
• Use a faster model.
• Increase llm.timeoutMs.

{
  "llm": {
    "timeoutMs": 120000
  }
}

Could not reach provider endpoint

Check:

• llm.baseUrl
• local network access
• DNS
• VPN/proxy settings
• provider status

Provider authentication failed

Check:

• the API key value in .bestie/.env
• the env var name in llm.apiKeyEnv
• provider account access

Do not paste API keys into issues, logs, screenshots, or chat.

Provider returned an unusable response

Confirm the configured model supports OpenAI-compatible chat completions.

Telegram issues

bestie telegram says Telegram is not enabled

Run setup:

bestie telegram setup

Or check .bestie/config.json:

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botTokenEnv": "BESTIE_TELEGRAM_BOT_TOKEN",
      "ownerUserId": "123456789"
    }
  }
}

Bot does not reply

Check:

• BESTIE_TELEGRAM_BOT_TOKEN exists in .bestie/.env.
• ownerUserId matches your Telegram user id.
• You are messaging the bot from the owner account.
• bestie telegram is running.

Run:

bestie doctor
bestie doctor --telegram-connect

--telegram-connect performs an explicit network check against Telegram getMe.

Non-owner messages are ignored

That is expected. Telegram MVP is owner-only by default.

Telegram attachments are not parsed

Check attachment config:

• downloadPolicy
• maxBytes
• parseMaxBytes
• allowedMimeTypes
• visionPolicy
• transcriptionPolicy

Text, PDF, and DOCX attachments can get bounded text previews. Vision and transcription require explicit opt-in config.

Voice transcription issues

Voice messages download but do not transcribe

Run Doctor:

bestie doctor

Check that these exist:

.bestie/tools/whisper-bin/whisper-cli
.bestie/tools/local-whisper-transcribe.sh
.bestie/models/ggml-small.bin

Also make sure ffmpeg is installed and available on PATH.

Vietnamese transcription is poor

Use ggml-small.bin or better. ggml-tiny.bin is faster but often too inaccurate for Vietnamese voice chat.

Make sure local whisper args include Vietnamese language selection:

{
  "args": ["{modelPath}", "{audioPath}", "-l", "vi"]
}

Memory issues

Bestie does not remember something

Check memory status:

bestie memory status
bestie memory list

If memory is paused:

bestie memory resume

If memory.writePolicy is ask, proposed memories may be waiting for approval:

bestie memory pending

Bestie remembered the wrong thing

Inspect and edit or forget the memory:

bestie memory inspect 1
bestie memory edit 1 "Updated memory text."
bestie memory forget 1

Clear local memory

Export first if needed:

bestie memory export
bestie memory clear --yes

MCP and tools issues

MCP tool does not run

Bestie requires local tool classification before read-only MCP calls.

Check server config:

bestie mcp list
bestie mcp show <server-name>

Classify a read-only tool:

bestie mcp classify <server-name> <tool-name> --category read

Tool requires approval

That is expected for tools outside the default read-only path. Use --ask to force a one-time approval prompt for a read call:

bestie mcp call <server-name> <tool-name> --read --ask --json '{"path":"README.md"}'

Secrets appear in output

Stop and treat it as a bug. Do not share the output publicly. Bestie should redact secret-like values from logs, Doctor reports, and channel summaries.

Reset local generated state

For local development, Doctor safe fixes can recreate folders and initialize SQLite:

bestie doctor --fix

Avoid deleting .bestie/ unless you intentionally want to remove config, memory, logs, and local state.