> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fs.soquincy.qzz.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Common Freesona Errors and Failures

> Fix the most common Freesona issues — bot won't start, commands not responding, AI errors, timezone problems, and media download failures.

If something isn't working, this page covers the most common issues and how to fix them. Start with the section that matches your symptom.

<AccordionGroup>
  <Accordion title="Bot won't start / no output">
    1. Check that `BOT_TOKEN` is set correctly in `.env` — paste it directly with no extra whitespace or quotes.
    2. Check that `CHANNEL_ID` is a valid integer channel ID, not a channel name.
    3. Run `python main.py` directly in your terminal and read the error output — the startup logs will point to the exact problem.
    4. Verify all required dependencies are installed: `pip install -r requirements.txt`.
  </Accordion>

  <Accordion title="Slash commands not showing in Discord">
    1. Slash commands need to be synced after first launch or after changes.
    2. Run `/sync` as the Bot Owner to push global slash commands to Discord.
    3. Discord can take a few minutes to propagate global slash commands — wait and refresh your client.
    4. Make sure you invited the bot with the `applications.commands` scope. Re-invite with that scope if needed.
  </Accordion>

  <Accordion title="AI commands not responding">
    1. Check that the `genai` module is enabled: `/module list`.
    2. Verify your API key is set in `.env` for the provider you chose (`GOOGLE_API_KEY`, `OPENAI_API_KEY`, etc.).
    3. Confirm `AI_PROVIDER` in `.env` matches the key you provided — for example, if you set `GROQ_API_KEY`, set `AI_PROVIDER=groq`.
    4. Run `/provider show` to confirm the active provider matches your intent.
    5. Check the bot console output for API error messages — rate limit, authentication, and quota errors are printed there.
  </Accordion>

  <Accordion title="Bot responds in the wrong channel or everywhere">
    1. Use `/setchannel #channel` to restrict conversation replies to a specific channel.
    2. Check the current chat mode: use `/chatmode mentions` to limit replies to direct mentions and replies to the bot only.
    3. If autonomous mode is active, disable it with `/autonomy off` to stop unsolicited replies in non-conversation channels.
  </Accordion>

  <Accordion title="Timezone-related errors on Windows">
    1. Python's `zoneinfo` module may lack IANA timezone data on Windows.
    2. Install `tzdata`: run `.venv\Scripts\pip.exe install tzdata` (or `pip install tzdata` if you're not using a virtual environment).
    3. `tzdata` is included in `requirements.txt`, so a clean `pip install -r requirements.txt` should handle this automatically.
  </Accordion>

  <Accordion title="~math doesn't work">
    1. `~math` requires `WOLFRAM_APPID_SHORT` to be set in `.env`. Get an AppID from [developer.wolframalpha.com](https://developer.wolframalpha.com).
    2. If the Short Answer API returns no result, `WOLFRAM_APPID_LLM` is used as a fallback — set both for full coverage.
    3. Check that the `math` module is enabled: `/module list`.
  </Accordion>

  <Accordion title="~download / ~audio fails">
    1. Both commands require `yt-dlp` and `ffmpeg` to be installed and available on your system `PATH`.
    2. Check that the `ytdlp` module is enabled: `/module list`.
    3. Discord has a 10 MB upload limit for free servers — large video files will fail after download. Try a shorter clip or lower resolution source.
    4. A per-user cooldown of 30 seconds applies between downloads — wait and try again.
    5. If compression still produces an oversized file, lower the target: `/config set ytdlp_compress_target_mb 8.0`.
  </Accordion>

  <Accordion title="~separate returns no result or times out">
    1. `~separate` requires `MVSEP_API_KEY` to be set in `.env`.
    2. Check that both the `mvsep` and `ytdlp` modules are enabled — `mvsep` depends on `ytdlp` for platform URL downloads: `/module list`.
    3. MVSEP's free tier allows one separation job at a time — if a job is already in progress, wait for it to finish before submitting another.
    4. For long audio files, increase the polling timeout: `/config set mvsep_poll_timeout 600`.
    5. If you configured webhook-based completion, verify `MVSEP_WEBHOOK_URL` is publicly accessible and reachable by MVSEP's servers.
  </Accordion>

  <Accordion title="Data lost after redeployment on Railway or Render">
    1. Without a persistent volume, `config.json`, `memory.db`, `warnings.db`, and persona files are wiped on every redeploy.
    2. Mount a volume at `/data` in your hosting platform's settings.
    3. Set all file path environment variables to their `/data/` equivalents — see the [Environment Variables](/reference/environment-variables) reference for the full list.
  </Accordion>

  <Accordion title="Memory and persona files not persisting between restarts">
    1. Confirm `CONFIG_FILE_PATH`, `MEMORY_FILE_PATH`, `AI_PERSONA_JSON_FILE`, and `WARNINGS_FILE_PATH` all point to a writeable location.
    2. On cloud hosts (Railway, Render), these paths must be inside a mounted persistent volume.
    3. Check that the bot process has write permissions to the target directory.
  </Accordion>

  <Accordion title="Prompt injection detection altering my messages">
    Freesona detects common prompt injection phrases — `"ignore previous instructions"`, `"jailbreak"`, `"developer mode"`, and similar — and sanitizes them before the prompt reaches the AI model. The prompt is neutralized rather than silently dropped, and the bot's output is also checked for injection artifacts. If a prompt is being altered, look at the bot console output for a security log message. This is intentional behavior designed to protect your persona from being overridden.
  </Accordion>
</AccordionGroup>

## Still Stuck?

If none of the above resolves your issue, get help from the community:

* **GitHub Issues** — open a bug report or check existing issues at [github.com/soquincy/Freesona/issues](https://github.com/soquincy/Freesona/issues)
* **Discord Server** — ask in the support channel at [discord.gg/vXPRs2cHSE](https://discord.gg/vXPRs2cHSE)