메뉴
Common issues and solutions for Alfira — bot problems, authentication failures, music source errors, database issues, and reset procedures. Use when debugging any Alfira problem or investigating error reports.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | alfira-troubleshooting |
| description | Common issues and solutions for Alfira — bot problems, authentication failures, music source errors, database issues, and reset procedures. Use when debugging any Alfira problem or investigating error reports. |
Symptoms: Bot doesn't appear in voice channel when using the Play button.
Solutions:
DISCORD_BOT_TOKEN is correct.docker compose logs alfiraSymptoms: Bot joins but no audio is heard.
Solutions:
docker compose logs alfira[NodeLink] prefix in logs to see NodeLink startup status.Symptoms: "Invalid redirect_uri" error during Discord login.
Solutions:
DISCORD_REDIRECT_URI matches exactly in:
.env filehttps:// in production.Symptoms: Logged in but the "+ Request Song" button is missing from the Songs page.
Solutions:
Symptoms: Logged in but can't approve/deny requests, can't edit/delete songs, can't access admin settings.
Solutions:
docker compose logs alfira | grep -i admin to verify the bot detects your admin status.Symptoms: /play, /skip, etc. give "The application did not respond" errors.
Cause: Alfira removed Discord slash commands in April 2026 — all playback control is exclusively through the web UI. Discord may still have old commands cached.
Solutions:
docker compose restart alfira
bun run discord:unregister-commands
.env with DISCORD_BOT_TOKEN, DISCORD_CLIENT_ID, GUILD_ID)Symptoms: Pasting a URL from these sources returns "Could not fetch track info" or similar error.
Cause: These sources require API credentials that aren't configured.
Solutions:
.env file (see Installation Guide).docker compose restart alfiraSymptoms: Pasting a valid URL from a supported source but getting a validation error.
Solutions:
Symptoms: API crashes with "database not found" or permission errors.
Solutions:
docker compose psdocker compose logs alfira/data volume is properly mounted and writable.docker compose down -v then docker compose up --buildWarning: This will delete all your data (playlists, songs, etc.).
# Stop and remove everything, including database
docker compose down -v
# Rebuild from scratch
docker compose up --build
docker compose logs -f alfiraAPI route structure, authentication flow, middleware, security headers, WebSocket auth, and response helpers. Use when working on routes/*.ts, middleware/requireAuth.ts, index.ts route wiring, or adding new API endpoints.
Server architecture, startup sequence, WebSocket pipeline, build/deploy cycle, shared package exports, and monorepo layout. Use when working on packages/server/src/index.ts, lib/socket.ts, startDiscord.ts, server config, or understanding how components connect.
NodeLink/Lavalink audio pipeline, GuildPlayer state machine, voice connection flow, track lifecycle events, and REST commands for player control. Use when working on lib/lavalink.ts, GuildPlayer.ts, lib/voice.ts, PlaybackCursor.ts, lib/applyNodeLinkFilter.ts, or any audio/playback feature.
SQLite + Drizzle ORM schema, homegrown migration runner, query patterns, tag system, and guild settings. Use when working on shared/db/schema.ts, migrations, lib/ensureTagsMigrated.ts, lib/tagCanonicalization.ts, or any database query.
React 19 + Tailwind CSS 4 web UI, component and page structure, API client, WebSocket client, virtual list pattern, and settings sections. Use when working on packages/web/src/, UI components, or frontend features.