Skip to main content

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.

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 for additional context.
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: 
    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, open your bot application, navigate to Bot, and confirm that Message Content Intent is toggled on under Privileged Gateway Intents.
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: 
    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.
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 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.
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 for the full list.
  • Run /settings view to confirm the current stored values match what you set.
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.
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: 
    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.
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: 
    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.
If none of the above resolves your issue, visit the FAQ for answers to broader questions about JoBot’s configuration and capabilities.