> ## Documentation Index
> Fetch the complete documentation index at: https://safia.maximusolution.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting SAFIA: Diagnose and Fix Bot Issues

> Diagnose and fix the most common problems with your SAFIA bot — from connection errors and rate limits to voice transcription and the admin dashboard.

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

<AccordionGroup>
  <Accordion title="Bot is not responding to messages">
    **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:**

    <Steps>
      <Step title="Check daemon status">
        ```bash theme={null}
        safia status
        ```

        If the bot process shows as stopped, start it:

        ```bash theme={null}
        safia start
        ```
      </Step>

      <Step title="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:

        ```bash theme={null}
        ls -l data/cache.db
        ```

        If the file is missing or the directory is not writable, create it and fix permissions:

        ```bash theme={null}
        mkdir -p data
        chmod u+rw data
        ```
      </Step>

      <Step title="Check your bot token">
        Open your `.env` file and confirm `TELEGRAM_BOT_TOKEN` is set to the token from [@BotFather](https://t.me/BotFather). Tokens look like `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`. If you regenerated the token in BotFather, update `.env` and restart:

        ```bash theme={null}
        safia restart
        ```
      </Step>

      <Step title="Check the logs for errors">
        ```bash theme={null}
        safia logs 50
        ```

        Look for lines containing `ERROR` or `Exception` that point to the root cause.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Cache file errors in the logs">
    **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:**

    <Steps>
      <Step title="Confirm the cache file path">
        Check `CACHE_DB_PATH` in your `.env` (default `data/cache.db`) and ensure the parent directory exists:

        ```bash theme={null}
        ls -l data/cache.db
        mkdir -p "$(dirname data/cache.db)"
        ```
      </Step>

      <Step title="Fix permissions">
        Make sure the user running SAFIA can read and write the cache file and its directory:

        ```bash theme={null}
        chmod u+rw data data/cache.db 2>/dev/null || true
        ```
      </Step>

      <Step title="Check available disk space">
        ```bash theme={null}
        df -h .
        ```

        Free up space if the volume is full — the persisted cache cannot grow on a full disk.
      </Step>

      <Step title="Restart after making changes">
        ```bash theme={null}
        safia restart
        ```
      </Step>
    </Steps>

    <Note>
      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.
    </Note>
  </Accordion>

  <Accordion title="'User not authorized' — access denied message">
    **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:**

    <Steps>
      <Step title="Note your Telegram user ID">
        The bot's rejection message includes your ID, for example: `Your Telegram ID: 123456789`.
      </Step>

      <Step title="Add the ID in the admin dashboard">
        Open the dashboard at [http://127.0.0.1:5454](http://127.0.0.1:5454), navigate to **Users**, and add the Telegram ID to the allowlist.
      </Step>

      <Step title="Try messaging the bot again">
        No restart is required — the change takes effect immediately.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="LLM API errors — bot replies with an error or stays silent">
    **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:**

    <Steps>
      <Step title="Open your configuration">
        ```bash theme={null}
        safia config
        ```
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Check the logs">
        ```bash theme={null}
        safia logs 30
        ```

        An HTTP 401 response means the key is wrong. An HTTP 404 response usually means the model name is wrong.
      </Step>

      <Step title="Restart after saving changes">
        ```bash theme={null}
        safia restart
        ```
      </Step>
    </Steps>

    <Tip>
      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`).
    </Tip>
  </Accordion>

  <Accordion title="Slow startup — bot takes a long time to become available">
    **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:**

    ```bash theme={null}
    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.

    <Note>
      If the download stalls or fails due to a network interruption, delete the incomplete model files and restart SAFIA to retry the download automatically.
    </Note>
  </Accordion>

  <Accordion title="Reminders are not being sent">
    **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:**

    <Steps>
      <Step title="Check the setting">
        ```bash theme={null}
        safia config
        ```

        Look for `REMINDER_ENABLED`. It must be `true` (not `false`, empty, or missing).
      </Step>

      <Step title="Set it if needed">
        Add or update the line in your `.env`:

        ```text theme={null}
        REMINDER_ENABLED=true
        ```
      </Step>

      <Step title="Restart SAFIA">
        ```bash theme={null}
        safia restart
        ```
      </Step>
    </Steps>

    <Note>
      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`.
    </Note>
  </Accordion>
</AccordionGroup>

***

## Voice & Photos

<AccordionGroup>
  <Accordion title="Voice messages are not being transcribed">
    **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:**

    <Steps>
      <Step title="Get a Groq API key">
        Sign up at [console.groq.com](https://console.groq.com) and create a free API key.
      </Step>

      <Step title="Add the key to your .env">
        ```bash theme={null}
        safia config
        ```

        Add or update:

        ```text theme={null}
        GROQ_API_KEY=gsk_your_key_here
        ```
      </Step>

      <Step title="Restart SAFIA">
        ```bash theme={null}
        safia restart
        ```
      </Step>

      <Step title="Verify in the logs">
        Send a short voice message and watch:

        ```bash theme={null}
        safia logs 20
        ```

        A successful transcription logs the detected text before the bot responds.
      </Step>
    </Steps>

    <Warning>
      `GROQ_API_KEY` is required for voice transcription **regardless** of which LLM provider you use for chat. There is currently no alternative transcription backend.
    </Warning>
  </Accordion>

  <Accordion title="Photos of receipts are not being processed">
    **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:**

    <Steps>
      <Step title="Confirm LLM_API_KEY is set">
        ```bash theme={null}
        safia config
        ```

        `LLM_API_KEY` must be present and valid. If it's empty, photo scanning will always report that it's not enabled.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Check the logs for API errors">
        ```bash theme={null}
        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.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Admin Dashboard

<AccordionGroup>
  <Accordion title="Admin dashboard is not accessible at http://127.0.0.1:5454">
    **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:**

    <Steps>
      <Step title="Check daemon status">
        ```bash theme={null}
        safia status
        ```

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

        ```bash theme={null}
        safia start
        ```
      </Step>

      <Step title="Check whether the port is in use">
        ```bash theme={null}
        # Linux / macOS
        lsof -i :5454

        # Windows (PowerShell)
        netstat -ano | findstr :5454
        ```

        If another process is occupying port 5454, stop it or reconfigure SAFIA.
      </Step>

      <Step title="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:

        ```bash theme={null}
        ssh -L 5454:127.0.0.1:5454 your-server
        ```

        Then open `http://127.0.0.1:5454` in your local browser.
      </Step>

      <Step title="Check the logs">
        ```bash theme={null}
        safia logs 30
        ```

        Any dashboard startup errors will appear here.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Admin dashboard login is not working">
    **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:**

    <Steps>
      <Step title="Check your .env credentials">
        ```bash theme={null}
        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.
      </Step>

      <Step title="Set a Flask secret key">
        A missing `FLASK_SECRET_KEY` can break session handling. Add a long random string to your `.env`:

        ```text theme={null}
        FLASK_SECRET_KEY=some-long-random-string
        ```
      </Step>

      <Step title="Restart after changes">
        ```bash theme={null}
        safia restart
        ```
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

***

## Rate Limits

<AccordionGroup>
  <Accordion title="'Rate limit exceeded' — reached the daily message cap">
    **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`:
      ```text theme={null}
      DAILY_MESSAGE_LIMIT=2000
      ```
      Then restart:
      ```bash theme={null}
      safia restart
      ```
    * **Reset manually** — an admin can clear a user's rate-limit counter from the dashboard at [http://127.0.0.1:5454](http://127.0.0.1:5454) (under **Users → Reset rate limit**), or by deleting the cached counter directly from the persisted cache database:
      ```bash theme={null}
      sqlite3 data/cache.db "DELETE FROM cache WHERE key = 'safia:rate:<telegram_user_id>';"
      safia restart
      ```

    <Note>
      Voice messages and photo scans each count as one message toward the daily limit, the same as a text message.
    </Note>
  </Accordion>
</AccordionGroup>