Troubleshooting

Start with Doctor whenever Bestie behaves unexpectedly. It checks local runtime paths, configuration, secret presence, and enabled capability diagnostics without printing secret values.

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:

• the active LLM profile’s 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 the active LLM profile’s apiKeyEnv
• provider account access

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

Provider returned an unusable response

Confirm the selected model ref is supported by the configured provider profile. Use bestie llm test --model <provider/model> when you need a focused provider check.

Telegram issues

bestie channels telegram says Telegram is not enabled

Run setup:

bestie channels 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 channels 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; remove the secret from any copied material and rotate it when exposure is plausible. 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.