Troubleshooting

Common AttendiBot issues organized by symptom. For setup guidance, see Getting Started.

Sessions not being recorded

Signing is locked

Symptom: Members join voice but no sessions appear in stats or leaderboards.

Cause: Signing keys are encrypted at rest. After every backend restart, keys must be unlocked.

Fix:

1. Dashboard → Signing → Unlock signing
2. Or Discord: /admin unlock-signing passphrase:your-passphrase
3. Confirm with /admin signing-status — should show "unlocked in memory"

Signing not configured

Symptom: /admin signing-status shows "not configured".

Fix: Generate keys first:

• Dashboard → Signing → Generate keys
• Or /admin generate-keys passphrase:your-passphrase

Tracking mode is Off

Symptom: Bot is online but nothing tracks.

Fix: Set tracking mode to Allowlist, Denylist, or All:

• Dashboard → Settings → Tracking
• Or /admin tracking-mode mode:All

Channel not tracked (Allowlist mode)

Symptom: Some channels track, others don't.

Fix: Add channels to the allowlist:

• Dashboard → Settings → Tracking → Add channel
• Or /admin track-channel action:Add channel:#YourChannel

Session below minimum duration

Symptom: Brief joins don't create sessions.

Fix: Check Minimum session duration in fairness settings. Set to 0 to record all sessions.

Channel excluded (Denylist mode)

Symptom: Specific channels never track.

Fix: Remove the channel from the denylist or switch to Allowlist/All mode.

Commands not appearing in Discord

Global registration delay

Symptom: Slash commands missing after first bot start.

Cause: Without DISCORD_GUILD_ID, commands register globally (up to 1 hour).

Fix: Set DISCORD_GUILD_ID in backend .env for instant guild registration during development. Restart the bot.

Missing applications.commands scope

Symptom: Bot is in server but no slash commands at all.

Fix: Re-invite the bot with both bot and applications.commands scopes. See Discord Setup.

Dashboard issues

Dashboard can't reach the API

Symptom: Dashboard pages show errors or empty data; health check fails from web container.

Cause: Wrong ATTENDIBOT_API_BASE_URL — often set to public site URL or /api instead of internal backend hostname.

Fix:

ATTENDIBOT_API_BASE_URL=http://<backend-service-name>:8080
ATTENDIBOT_API_INTERNAL_SECRET=<same as backend API_INTERNAL_SECRET>

Verify from the web container:

node -e "fetch(process.env.ATTENDIBOT_API_BASE_URL+'/health').then(r=>r.text()).then(console.log)"

Do not route all public /api/* to the backend — this breaks Auth.js routes at /api/auth/*.

OAuth sign-in fails

Symptom: "Invalid redirect URI" or sign-in loop.

Fix:

1. Add exact redirect URI in Discord Developer Portal: {NEXT_PUBLIC_SITE_URL}/api/auth/callback/discord
2. Verify AUTH_DISCORD_ID and AUTH_DISCORD_SECRET match the portal
3. Confirm AUTH_SECRET is set

Server not listed in guild picker

Symptom: Your server doesn't appear after sign-in.

Fix: You need Manage Server permission on that guild. Sign in with the account that has admin access.

"Add to Discord" button broken

Symptom: Button opens Discord with "Invalid Form Body" or missing client_id.

Fix: Set at least one of:

• NEXT_PUBLIC_DISCORD_INVITE_URL (full invite URL)
• NEXT_PUBLIC_DISCORD_CLIENT_ID or AUTH_DISCORD_ID
• DISCORD_INVITE_URL (runtime override)

Verify after deploy: view page source, search for oauth2/authorize, confirm client_id= is present.

Bot restart requires re-unlock

Symptom: Sessions stop recording after deploy or container restart.

Expected behavior: Signing keys are never persisted in memory. Unlock is required after every restart.

Fix: Unlock signing immediately after each deploy. Consider alerting if signing stays locked.

Database connection errors

Symptom: Bot fails to start; /health returns unhealthy.

Fix:

1. Verify Postgres is running: docker compose up db -d
2. Check DATABASE_URL matches your Postgres credentials
3. In production, ensure ENVIRONMENT=production and DATABASE_URL is set
4. Default dev URL: postgres://attendibot:attendibot@localhost:5433/attendibot

Log messages not posting

Symptom: Log destinations configured but no embeds in Discord channels.

Fix:

1. Verify the bot can Send Messages and Embed Links in the log channel
2. Check log type is enabled on the destination (/admin logs list)
3. For periodic logs (Leaderboard, AttendanceSummary), confirm interval is configured

Verification returns invalid

Symptom: Public verifier or /admin verify-session returns invalid.

Possible causes:

1. Session UUID is wrong or from a different server
2. Keys were re-generated after the session was signed
3. Database was restored from backup without matching keys

Production secret errors

Symptom: Backend refuses to start in production.

Fix: In production (ENVIRONMENT=production), these must be set to non-default values:

• DATABASE_URL
• WEBHOOK_SECRET
• API_INTERNAL_SECRET

Getting help

• Review FAQ
• Check Discord Setup
• Visit attendibot.com/docs
• Contact support via the Discord link in the site footer (when configured)