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
  • Redis is not running (SAFIA cannot start without it)
  • The bot token is invalid or has been revoked
Steps to fix:
1

Check daemon status

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

Verify Redis is running

redis-cli ping
A healthy Redis responds with PONG. If the command fails, start Redis using the method appropriate for your OS:
# Linux (systemd)
sudo systemctl start redis

# macOS (Homebrew)
brew services start redis
On Windows, start Memurai from the system tray or run net start Memurai in an elevated PowerShell window.
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:
safia restart
4

Check the logs for errors

safia logs 50
Look for lines containing ERROR or Exception that point to the root cause.
Symptom: The logs show messages about a connection being refused or a failure to reach Redis at localhost:6379.Likely cause: Redis is not running, or the REDIS_URL in your .env points to the wrong host or port.Steps to fix:
1

Confirm Redis is running

redis-cli ping
A healthy Redis responds with PONG. If the command fails, start Redis using the method appropriate for your OS (see the previous entry).
2

Check REDIS_URL in your .env

The default is redis://localhost:6379/0. If you changed the port or are connecting to a remote Redis instance, update this value:
safia config
Set REDIS_URL to match your actual Redis address.
3

Restart after making changes

safia restart
On Windows, SAFIA does not install Redis automatically. You must run Redis separately via Memurai, WSL, or Docker (docker run -d -p 6379:6379 --name safia-redis redis:7-alpine) before starting SAFIA.
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

safia config
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

safia logs 30
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

safia restart
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:
safia logs 20
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

safia config
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:
REMINDER_ENABLED=true
3

Restart SAFIA

safia restart
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

safia config
Add or update:
GROQ_API_KEY=gsk_your_key_here
3

Restart SAFIA

safia restart
4

Verify in the logs

Send a short voice message and watch:
safia logs 20
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

safia config
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

safia logs 30
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

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

Check whether the port is in use

# Linux / macOS
lsof -i :5454

# Windows (PowerShell)
netstat -ano | findstr :5454
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:
ssh -L 5454:127.0.0.1:5454 your-server
Then open http://127.0.0.1:5454 in your local browser.
4

Check the logs

safia logs 30
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

safia config
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:
FLASK_SECRET_KEY=some-long-random-string
3

Restart after changes

safia restart

​
Rate Limits

Symptom: The bot replies: “You’ve reached the daily limit of 25 messages. Please try again tomorrow.”Cause: SAFIA enforces a limit of 25 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: 
    DAILY_MESSAGE_LIMIT=50
    Then restart: 
    safia restart
  • Reset manually — an admin can clear the rate-limit counter for a specific user from the Redis CLI: 
    redis-cli DEL safia:rate:<telegram_user_id>
Voice messages and photo scans each count as one message toward the daily limit, the same as a text message.