Troubleshooting

Common issues and how to resolve them.

---

Bot Issues

Bot is offline or not responding

Symptoms: The bot appears offline, slash commands don't show up, or commands get no response.

Solutions:

1. Check that the bot process is running (Docker container status, process manager)

2. Verify the DISCORD_TOKEN environment variable is correct

3. Check the bot logs for connection errors or crashes

4. Ensure the bot has network access to Discord's API (discord.com)

5. If using Redis, verify Redis is accessible — the bot falls back to in-memory caching but may behave unexpectedly if Redis was expected

Slash commands not appearing

Symptoms: Typing / doesn't show any Ticketo commands.

Solutions:

1. Wait up to 1 hour — Discord caches slash commands globally and guild-specific registration may take time

2. Re-invite the bot with the applications.commands scope

3. Check that the bot has the Use Application Commands permission in the channel

4. Restart the bot — commands are registered on startup

Bot can't create channels

Symptoms: Error when creating tickets, "Missing Permissions" in logs.

Solutions:

1. Verify the bot has Manage Channels permission at the server level

2. Check that the bot has Manage Roles permission (needed for channel permission overwrites)

3. Ensure the target category isn't full (Discord limit: 50 channels per category)

4. If using thread-based tickets, ensure the bot has Create Private Threads and Manage Threads permissions

Bot can't send messages in ticket channels

Solutions:

1. The bot needs Send Messages, Embed Links, and Attach Files permissions

2. Check for channel-level permission overwrites that may block the bot

3. If the channel is a thread, ensure the bot has Send Messages in Threads permission

---

Dashboard Issues

Can't access the dashboard

Symptoms: Dashboard shows a login error, blank page, or 403 error.

Solutions:

1. Ensure you're logged in with a Discord account that has Manage Server permission in the target server

2. Clear browser cookies and re-authenticate

3. Check that the HTTP_EXTERNAL environment variable matches the URL you're accessing

4. Verify the API service is running and accessible

5. If behind Nginx, check that the reverse proxy is correctly forwarding requests

Dashboard shows "No servers"

Solutions:

1. The bot must be in the server AND you must have Manage Server permission

2. Try logging out and logging back in to refresh your guild list

3. The DISCORD_OAUTH_CLIENT_ID and DISCORD_OAUTH_CLIENT_SECRET must be correctly configured

Settings not saving

Solutions:

1. Check browser console for API errors

2. Verify the API service is running

3. Ensure the database is accessible and not full

4. Check that you have the required permission level (admin)

---

Ticket Issues

Users can't create tickets

Symptoms: Users click the panel button but no ticket is created.

Solutions:

1. Check that the bot has Manage Channels and Manage Roles permissions

2. Verify the ticket category parent channel exists in Discord

3. Check if the user is on the blocklist

4. If required roles are set on the panel option, verify the user has one of them

5. Check if the panel option is disabled in the dashboard

6. Ensure the Discord category isn't full (max 50 channels)

Ticket channel permissions are wrong

Solutions:

1. The bot needs Manage Roles permission to set channel overwrites

2. Check that support roles are correctly configured in the dashboard

3. If the bot's role is below other roles in the hierarchy, it can't manage those roles' permissions

Auto-close isn't working

Symptoms: Tickets stay open despite having auto-close configured.

Solutions:

1. Auto-close runs on a 15-minute background check interval — it isn't instant

2. Verify autoClose is enabled in the category settings

3. Check that the configured duration is correct

4. Any message in the ticket resets the inactivity timer

5. Ensure the bot process hasn't restarted recently (stale ticket data is reloaded on startup)

Close requires reason but I can't enter one

If closeRequiresReason is enabled, you'll be shown a modal to enter a reason when closing. If the modal doesn't appear:

1. Try using /close instead of the button

2. Check your Discord client is up to date (modals require a recent client)

---

Transcript Issues

Transcripts aren't being generated

Solutions:

1. Ensure archive is enabled in the category settings

2. The ENCRYPTION_KEY environment variable must be set (48+ character hex string)

3. If using PostgreSQL, check that the Transcript table exists (run migrations)

4. Check logs for encryption/decryption errors

Transcript page is blank or broken

Solutions:

1. Ensure the portal service is running and accessible

2. Check that HTTP_EXTERNAL is set correctly

3. Verify the transcript ID is valid (21-character string)

4. If the transcript was created before an encryption key change, the data is unrecoverable

Lost encryption key

If you've lost or changed the ENCRYPTION_KEY, all previously encrypted data is unrecoverable. This includes:

• Transcript message content

• Usernames and display names

• Ticket topics

• Close reasons and feedback comments

There is no way to recover this data. Always back up your encryption key.

---

Database Issues

Migration errors on startup

Solutions:

1. Run npx prisma migrate deploy with the correct DATABASE_URL

2. Ensure the database server is running and accessible

3. Check that the database user has permission to create/alter tables

4. For PostgreSQL, ensure the database exists before running migrations

Database connection failures

Solutions:

1. Verify the DATABASE_URL format:

   • PostgreSQL: postgresql://user:password@host:5432/database

   • MySQL: mysql://user:password@host:3306/database

   • SQLite: file:./database.db

2. Check network connectivity between the bot and database server

3. If using Docker, ensure the database service is on the same network

4. Check that the database server is accepting connections

---

Docker / Deployment Issues

Services can't communicate

Solutions:

1. All services must be on the same Docker network

2. Use service names (not localhost) for inter-service communication in Docker

3. Check that ports are correctly mapped in docker-compose.yml

4. Verify Nginx configuration forwards requests to the correct upstream

Port conflicts

Solutions:

1. The default ports are: bot/API on 8169, portal on 3000, Nginx on 80/443

2. Change port mappings in docker-compose.yml if conflicts exist

3. In 3-service mode, the bot uses SKIP_HTTP=true and doesn't bind a port

Redis connection issues

Solutions:

1. Check that Redis is running: redis-cli ping should return PONG

2. If using a password, set REDIS_PASSWORD in the environment

3. The default REDIS_URL is redis://localhost:6379

4. In Docker, use the Redis service name: redis://redis:6379

---

Getting Help

If none of the above solutions work:

1. Check the bot logs for specific error messages

2. Review the Environment Variables guide to verify your configuration

3. Visit the support server for community help