Troubleshooting

Use this page when the bot does not start or a ticket workflow fails.

Bot Fails to Start

Check:

• config/.env exists.
• DISCORD_TOKEN is set.
• DB_FILE_NAME is set.
• config/config.ts exists.
• clientId and guildId are real IDs.
• The bot is invited to the configured guild.

Run:

bun run typecheck

Then start again:

bun run start

Configured Guild Not Found

The bot validates the configured guild on startup.

Fix:

• Confirm guildId is the server ID, not a channel ID.
• Confirm the bot was invited to that server.
• Confirm the token belongs to the same application as clientId.

Missing Permissions

The bot warns if it does not have Administrator.

If you do not use Administrator, check that the bot can:

• Create channels.
• Edit channels.
• Delete channels when enabled.
• Manage channel permission overwrites.
• View and send messages in panel/log/ticket channels.
• Read message history.
• Pin messages.

Slash Commands Do Not Appear

Restart the bot so it redeploys guild slash commands.

Then check:

• clientId is the application ID.
• guildId is correct.
• The bot was invited with the applications.commands scope.
• You are checking the same Discord server configured in guildId.

Panel Was Not Posted

Check startup logs and confirm:

• Every panels.*.channelId is correct.
• The panel channel is text-based.
• The bot can view and send messages in that channel.
• Every ticket type referenced by the panel exists in ticketTypes.
• The database is writable so panel message IDs can be tracked.

Users Cannot Open Tickets

Check:

• The user does not have a global blocked role.
• The user does not have a per-type blocked role.
• tickets.maxOpenPerUser has not been reached.
• The ticket type is included in the panel opener.
• The ticket type has a valid categoryId.
• The bot can create channels in that category.

Staff Cannot See Tickets

Check:

• Staff role IDs are listed in tickets.staffRoleIds or ticketTypes.*.staffRoleIds.
• The staff member actually has one of those roles.
• The bot can create permission overwrites.
• The category does not have conflicting permission behavior that blocks access.

Closing Fails

Check:

• The command or button is used in an open ticket channel.
• tickets.close.staffOnly is not blocking the user.
• If claims.mode is strict, the ticket is claimed by the closer.
• The bot can edit the channel, remove permission overwrites, send messages, and create DMs.
• Transcript upload is not blocking due to network issues.

Transcripts Fail

Check:

• tickets.close.createTranscript is true.
• TICKETPM_PASSKEY is set if needed.
• The bot can read message history.
• The host has outbound network access.
• Large attachments may take time to upload.

Docker Container Starts but Bot Does Nothing

Check:

docker compose logs -f bot

Common causes:

• config/.env missing.
• config/config.ts missing.
• DB_FILE_NAME points to the wrong path.
• Discord IDs still contain placeholder values.
• The bot token is invalid.