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

# Troubleshooting JoBot: common issues and fixes

> Solutions to common JoBot problems: bot not responding to mentions, music not playing, TTS not working, Subsonic errors, and settings not applying.

This page covers the most common problems people run into when self-hosting JoBot and how to fix them. Work through the checklist for whichever issue applies to you. If nothing here resolves your problem, check the [FAQ](/faq) for additional context.

<AccordionGroup>
  <Accordion title="Bot doesn't respond to mentions">
    JoBot is not responding when you mention it in a channel. Work through these checks in order:

    1. **Is the bot online?** Check that the Docker container is running:
       ```bash theme={null}
       docker compose ps
       ```
       The `jobot` service should show a status of `Up`. If it's not, start it with `docker compose up -d`.

    2. **Does the bot have channel permissions?** Open the channel settings in Discord and confirm the bot's role has both **Read Messages / View Channel** and **Send Messages** permissions. Without these, the bot can see nothing and respond to nothing.

    3. **Is the Message Content privileged intent enabled?** JoBot needs to read the content of messages to respond to mentions. Go to the [Discord Developer Portal](https://discord.com/developers/applications), open your bot application, navigate to **Bot**, and confirm that **Message Content Intent** is toggled on under Privileged Gateway Intents.
  </Accordion>

  <Accordion title="Music doesn't play / bot won't join voice">
    JoBot joins the voice channel but plays nothing, or refuses to join at all. Check the following:

    1. **Is the Lavalink container running?** JoBot depends on Lavalink for audio playback. Verify it's up:
       ```bash theme={null}
       docker compose ps
       ```
       The `lavalink` service must show `Up`. Restart it with `docker compose restart lavalink` if needed.

    2. **Do the passphrases match?** The `LAVALINK_PASSPHRASE` environment variable must be identical in both the `jobot` container and the `lavalink` container. A mismatch causes a silent authentication failure. Check both values in your `docker-compose.yml` or `.env` file.

    3. **Does the bot have voice channel permissions?** In the voice channel settings, confirm the bot's role has the **Connect** and **Speak** permissions. Without them, the bot cannot join or transmit audio.
  </Accordion>

  <Accordion title="TTS isn't working">
    The bot won't speak in voice even when triggered. Check the following:

    1. **Are the ElevenLabs credentials set?** Both `ElevenLabs__ApiKey` and `ElevenLabs__VoiceId` must be set in your environment. If either is missing or blank, TTS is silently disabled.

    2. **Is the bot already in a voice channel?** The bot must join a voice channel before it can speak. Use the appropriate join command first, then trigger TTS again.

    3. **Is your ElevenLabs plan active with available characters?** Check your [ElevenLabs account](https://elevenlabs.io) to confirm your subscription is active and you have remaining character quota for the current billing period. Exhausted quotas cause TTS requests to fail silently.
  </Accordion>

  <Accordion title="Settings changes aren't taking effect">
    You ran a `/settings set` command and it confirmed success, but the bot still behaves the same way.

    * **Settings apply immediately** — no bot restart is required. If the bot confirmed the change with an ephemeral message, the setting was saved.
    * **Check your permissions.** If the command appeared to succeed but nothing changed, verify you have the correct Discord permission for the command you used. See the [permissions summary](/commands/settings#permissions-summary) for the full list.
    * **Run `/settings view`** to confirm the current stored values match what you set.
  </Accordion>

  <Accordion title="Bot shows 'Failed to join voice channel'">
    JoBot attempted to join a voice channel but returned an error. Check the following:

    * Open the voice channel's permission settings in Discord and confirm the bot's role has both **Connect** and **Speak** permissions in that specific channel.
    * Channel-level permission overrides can block a role even if the server-level permissions are correct. Check for any explicit **Deny** overrides on the bot's role for that channel.
  </Accordion>

  <Accordion title="Subsonic music search returns no results">
    You searched for a song and the bot returned nothing, or an error, when Subsonic is your configured source.

    1. **Is `SUBSONIC_BASE_URL` correct?** Verify the URL in your environment config is the full base URL of your Subsonic server (e.g., `https://music.example.com`) and that it is reachable from inside the bot container:
       ```bash theme={null}
       docker compose exec jobot curl -s "$SUBSONIC_BASE_URL/rest/ping.view?u=user&p=pass&v=1.16.1&c=jobot&f=json"
       ```

    2. **Are the Subsonic credentials correct?** Double-check the username and password (or token) you have configured. An authentication failure returns an empty result set rather than an error in some Subsonic implementations.

    3. **Has your Subsonic library been indexed?** Log in to your Subsonic web UI and trigger a library scan under **Settings → Media Folders** if your library is new or has not been scanned recently.
  </Accordion>

  <Accordion title="Database errors on startup">
    JoBot fails to start and the logs show SQLite or migration errors.

    1. **Is `ConnectionStrings__JoBot` pointing to a writable path?** The path must be accessible and writable by the process running inside the container. Example:
       ```
       ConnectionStrings__JoBot=Data Source=/data/jobot.db
       ```

    2. **Is the volume mounted correctly?** The directory containing the database file must be mounted as a Docker volume so data persists between restarts and the container can write to it. Check your `docker-compose.yml`:
       ```yaml theme={null}
       volumes:
         - ./data:/data
       ```

    JoBot applies database migrations automatically on startup. If the file path or permissions are wrong, the bot will exit on start. Fix the path and volume mount, then run `docker compose up -d` again.
  </Accordion>
</AccordionGroup>

<Note>
  If none of the above resolves your issue, visit the [FAQ](/faq) for answers to broader questions about JoBot's configuration and capabilities.
</Note>