Skip to main content
When something isn’t working as expected, your first stop should always be the safia logs command. Running safia logs 50 prints the last 50 lines from the bot daemon and usually surfaces the exact error message you need. If the logs don’t point to an obvious cause, work through the relevant section below — each entry describes the symptom, explains what’s likely wrong, and walks you through the fix.

​
Bot Issues

Symptom: You send a message in Telegram and nothing happens — no reply, no “Thinking…” indicator.Likely causes:
  • The SAFIA daemon is not running
  • The bot token is invalid or has been revoked
  • The persistent cache file (CACHE_DB_PATH) is unwritable
Steps to fix:
1

Check daemon status

If the bot process shows as stopped, start it:
2

Verify the cache file is writable

SAFIA uses an in-memory cache that is persisted to SQLite at CACHE_DB_PATH (default data/cache.db). Make sure the directory exists and the user running SAFIA can write to it:
If the file is missing or the directory is not writable, create it and fix permissions:
3

Check your bot token

Open your .env file and confirm TELEGRAM_BOT_TOKEN is set to the token from @BotFather. Tokens look like 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ. If you regenerated the token in BotFather, update .env and restart:
4

Check the logs for errors

Look for lines containing ERROR or Exception that point to the root cause.
Symptom: The logs show messages about being unable to open, read, or write the SQLite cache database (default data/cache.db).Likely cause: The directory for CACHE_DB_PATH does not exist, the file is owned by another user, or the disk is full.Steps to fix:
1

Confirm the cache file path

Check CACHE_DB_PATH in your .env (default data/cache.db) and ensure the parent directory exists:
2

Fix permissions

Make sure the user running SAFIA can read and write the cache file and its directory:
3

Check available disk space

Free up space if the volume is full — the persisted cache cannot grow on a full disk.
4

Restart after making changes

SAFIA’s cache is in-memory at runtime and is flushed to SQLite (CACHE_DB_PATH) so state survives bot restarts. No external cache server needs to be installed or kept running.
Symptom: The bot replies with “Access denied — you are not authorized to use this bot” and shows your Telegram user ID.Likely cause: Your SAFIA instance is running in allowlist mode. Only user IDs that have been explicitly added in the admin dashboard can interact with the bot.Steps to fix:
1

Note your Telegram user ID

The bot’s rejection message includes your ID, for example: Your Telegram ID: 123456789.
2

Add the ID in the admin dashboard

Open the dashboard at http://127.0.0.1:5454, navigate to Users, and add the Telegram ID to the allowlist.
3

Try messaging the bot again

No restart is required — the change takes effect immediately.
Symptom: The bot either returns an error message such as “Something went wrong” or the “Thinking…” indicator appears but never resolves.Likely causes:
  • LLM_API_KEY is missing, wrong, or has been revoked
  • LLM_PROVIDER does not match the key you supplied
  • LLM_MODEL is set to a model name your provider does not recognize
Steps to fix:
1

Open your configuration

2

Verify your provider and key

Confirm LLM_PROVIDER is one of lunos, groq, openai, or custom, and that LLM_API_KEY is the correct key for that provider.
3

Check the model name

Each provider uses its own model naming convention. For example, Groq uses names like llama-3.3-70b-versatile, while OpenAI uses gpt-4o. Refer to your provider’s documentation and update LLM_MODEL accordingly.
4

Check the logs

An HTTP 401 response means the key is wrong. An HTTP 404 response usually means the model name is wrong.
5

Restart after saving changes

If you’re using a custom OpenAI-compatible provider, also set LLM_BASE_URL to the provider’s API endpoint (e.g. https://my-provider.com/v1).
Symptom: After running safia start, the bot is unresponsive for a minute or two before beginning to work normally.Likely cause: This is expected behaviour on the first run. SAFIA downloads the local embedding model (~120 MB) before it can process messages. Subsequent startups use the cached model and are much faster.What to do:
Watch the logs. You’ll see progress messages while the model downloads. Once you see the bot polling Telegram, it’s ready. The download only happens once; after that, the model is cached on disk.
If the download stalls or fails due to a network interruption, delete the incomplete model files and restart SAFIA to retry the download automatically.
Symptom: You set up a reminder through the bot but it never fires, even past the scheduled time.Likely cause: REMINDER_ENABLED is not set to true in your .env file.Steps to fix:
1

Check the setting

Look for REMINDER_ENABLED. It must be true (not false, empty, or missing).
2

Set it if needed

Add or update the line in your .env:
3

Restart SAFIA

By default, each user can have up to 10 active reminders, and SAFIA sends at most 15 reminder messages per user per day. You can raise these limits with REMINDER_MAX_PER_USER and REMINDER_MAX_SENDS_PER_DAY in .env.

​
Voice & Photos

Symptom: You send a voice message and the bot replies with “Sorry, I couldn’t understand the audio” or returns an error.Likely cause: Voice transcription uses Whisper via the Groq API, which requires a separate GROQ_API_KEY — even if you are using a different provider (Lunos, OpenAI, etc.) for chat.Steps to fix:
1

Get a Groq API key

Sign up at console.groq.com and create a free API key.
2

Add the key to your .env

Add or update:
3

Restart SAFIA

4

Verify in the logs

Send a short voice message and watch:
A successful transcription logs the detected text before the bot responds.
GROQ_API_KEY is required for voice transcription regardless of which LLM provider you use for chat. There is currently no alternative transcription backend.
Symptom: You send a photo and the bot replies with “Document photo scanning is not enabled” or “Couldn’t read a document from this photo.”Likely causes:
  • LLM_API_KEY is missing — without a valid API key, photo scanning is disabled entirely
  • The image is too blurry, dark, or cropped to extract text reliably
  • VISION_MODEL is set to a model that doesn’t support vision inputs
Steps to fix:
1

Confirm LLM_API_KEY is set

LLM_API_KEY must be present and valid. If it’s empty, photo scanning will always report that it’s not enabled.
2

Check VISION_MODEL

The default is mistralai/mistral-small-3.2-24b-instruct. If you’ve changed VISION_MODEL to a text-only model, vision extraction will fail. Reset it or choose a model your provider confirms supports image input.
3

Improve photo quality

If the API key and model are correct, the issue is likely the image itself. Ensure the receipt or document is well-lit, in focus, and fully visible within the frame. Avoid photos taken at steep angles.
4

Check the logs for API errors

HTTP 4xx errors indicate a key or model problem; a successful API call that returns no text indicates a photo quality issue.

​
Admin Dashboard

Symptom: The browser shows a connection refused error, times out, or displays a blank page when you visit http://127.0.0.1:5454.Likely causes:
  • The admin dashboard daemon is not running
  • Another process is already using port 5454
  • You are trying to access it from a remote machine (the dashboard only binds to localhost)
Steps to fix:
1

Check daemon status

Look for the dashboard/admin process. If it’s stopped, start everything:
2

Check whether the port is in use

If another process is occupying port 5454, stop it or reconfigure SAFIA.
3

Confirm you're accessing it from the same machine

The dashboard binds to 127.0.0.1 and is only reachable from the machine running SAFIA. If you need remote access, set up an SSH tunnel:
Then open http://127.0.0.1:5454 in your local browser.
4

Check the logs

Any dashboard startup errors will appear here.
Symptom: You visit the dashboard but can’t log in — incorrect password error, or the login page loops.Likely cause: ADMIN_USERNAME, ADMIN_PASSWORD, or FLASK_SECRET_KEY is not set in .env, or the values don’t match what you’re entering.Steps to fix:
1

Check your .env credentials

Confirm ADMIN_USERNAME and ADMIN_PASSWORD are both set to non-empty values. If they are blank, the dashboard may not enforce authentication correctly.
2

Set a Flask secret key

A missing FLASK_SECRET_KEY can break session handling. Add a long random string to your .env:
3

Restart after changes

​
Rate Limits

Symptom: The bot replies: “You’ve reached the daily limit of 1000 messages. Please try again tomorrow.”Cause: SAFIA enforces a limit of 1000 messages per user per day. The counter resets at UTC midnight every day.Your options:
  • Wait until UTC midnight — the counter resets automatically and you can send messages again.
  • Increase the limit — if you host SAFIA yourself and want a higher cap, update DAILY_MESSAGE_LIMIT in your .env:
    Then restart:
  • Reset manually — an admin can clear a user’s rate-limit counter from the dashboard at http://127.0.0.1:5454 (under Users → Reset rate limit), or by deleting the cached counter directly from the persisted cache database:
Voice messages and photo scans each count as one message toward the daily limit, the same as a text message.