Troubleshooting#

Start with the narrowest observable boundary: container health, application logs, reverse proxy, Discord configuration, then the browser. Avoid deleting data or regenerating credentials until the failure is understood.

Login loops or OAuth errors#

• Confirm PUBLIC_BASE_URL exactly matches the browser origin.
• Confirm the Discord redirect URI ends with /auth/discord/callback.
• Check system time, HTTPS validity, cookie security, and proxy forwarding headers.
• Verify the member belongs to an allowed guild and is invited to the instance.

Bot is offline or will not join#

• Check the bot token without printing it.
• Confirm the guild is in ALLOWED_GUILD_IDS.
• Verify the bot can view, connect, and speak in the selected channel.
• Check that the requester is present in that voice channel.

Upload or conversion fails#

• Compare the file size and duration with configured limits.
• Confirm free space remains above MIN_FREE_STORAGE_BYTES.
• Verify FFmpeg and ffprobe are available inside the container.
• Review the upload job in the dashboard and the related structured log event.

Playback fails#

• Test a known library track before testing an external URL.
• Re-check requester access if group membership or sharing changed.
• Confirm Discord voice connectivity and FFmpeg availability.
• For external URLs, verify yt-dlp can still obtain metadata within the timeout.

Get more evidence#

Capture the VTune version, timestamp, affected guild and channel IDs, sanitized log event names, and exact user-visible error. Never publish tokens, OAuth secrets, session cookies, setup links, media, or personal Discord metadata.