Skip to main content
If something is not working, this page covers the most common issues and how to fix them. Start with the section that matches your symptom.
  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.
This usually means there is a formatting error in your .env file:
  1. Remove Inline Comments: Ensure you don’t have comments on the same line as a value (e.g., MODEL_TEMPERATURE=0.7 # comment). Remove everything after the value.
  2. Avoid Empty Values: If a variable like LOG_CHANNEL_ID is defined but left blank (e.g., LOG_CHANNEL_ID=), either provide a value or remove the line entirely.
Freesona requires Python 3.10 or higher. This error occurs when using an older version (like 3.9) that does not support the new type union syntax.
  • Check your version: python --version
  • If it’s below 3.10, download and install the latest version from python.org.
This means your Python dependencies are not installed in the environment you are currently running.
  1. Use a Virtual Environment: It is highly recommended to use a venv to avoid conflicts.
  2. Install Requirements: After activating the venv, run:
  3. Verification: Ensure you see (.venv) in your terminal prompt before running python main.py.
  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.
  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.
  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.
  1. ~math requires WOLFRAM_APPID_SHORT to be set in .env. Get an AppID from 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.
  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.
  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.
  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 for the full list.
  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.
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. 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.

​
Still Stuck?

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