Discord Activity Troubleshooting Guide

cgen-dfdc88a5cfe843268a62e8a511df2e7d
2025-11-09 03:55:29 +00:00 · 2025-11-09 03:55:29 +00:00 · a54d8a9cad
commit a54d8a9cad
parent 196b15b72d
1 changed files with 209 additions and 0 deletions
--- a/docs/DISCORD-ACTIVITY-TROUBLESHOOTING.md
+++ b/docs/DISCORD-ACTIVITY-TROUBLESHOOTING.md
@ -0,0 +1,209 @@
+# Discord Activity Troubleshooting Guide
+
+## Error: 403 Forbidden on Directory API + X-Frame-Options Error
+
+### Symptoms
+- Discord Activity shows blank screen
+- Browser console shows: `GET https://discord.com/api/v9/application-directory-static/applications/578971245454950421?locale=en-US 403 (Forbidden)`
+- Browser console shows: `Refused to display 'https://578971245454950421.discordsays.com/' in a frame because it set 'X-Frame-Options' to 'sameorigin'`
+
+### Root Causes
+1. **Activities feature not enabled** in Discord Developer Portal
+2. **Activity URL not configured** in Discord Developer Portal
+3. **Interactions Endpoint URL not set** or not responding correctly
+4. **Missing OAuth2 configuration** for Activity scopes
+
+---
+
+## Solution: Step-by-Step Configuration
+
+### Step 1: Enable Activities Feature
+1. Go to **[Discord Developer Portal](https://discord.com/developers/applications)**
+2. Click on your app: **AeThex** (ID: `578971245454950421`)
+3. Navigate to **General Information** tab
+4. Scroll to **Activity Settings** section
+5. Look for "Enable Activities" button/toggle
+   - If you see it, click to enable
+   - If Activities is already enabled, proceed to Step 2
+
+### Step 2: Configure Activity URL
+1. In **Activity Settings**, you should now see:
+   - **Activity URL** field
+   - Set it to: `https://aethex.dev/activity`
+2. **Interactions Endpoint URL**:
+   - Set to: `https://aethex.dev/api/discord/interactions`
+3. **Instance URL** (if present):
+   - Set to: `https://aethex.dev`
+4. Click **Save**
+5. **Wait 1-2 minutes** for Discord to process the configuration
+
+### Step 3: Verify Interactions Endpoint
+Discord will test your Interactions Endpoint by sending a PING request.
+
+**Expected behavior:**
+- You should see a green checkmark next to the Interactions Endpoint URL
+- If it fails, check:
+  1. Is `https://aethex.dev/api/discord/interactions` responding?
+  2. Is `DISCORD_PUBLIC_KEY` set in your environment?
+  3. Run this to test: `curl -X POST https://aethex.dev/api/discord/interactions -H "Content-Type: application/json" -d '{}'`
+
+### Step 4: Check OAuth2 Settings
+1. Go to **OAuth2** → **General**
+2. Verify **Client ID**: `578971245454950421`
+3. Ensure **Client Secret** is populated
+4. Go to **OAuth2** → **Scopes**
+5. Check that at least these scopes are selected:
+   - ✅ `identify`
+   - ✅ `guilds`
+
+### Step 5: Test the Activity
+1. Add your bot to a test Discord server:
+   - Go to **OAuth2** → **URL Generator**
+   - Select scopes: `bot`, `applications.commands`
+   - Copy the generated URL and open it in browser
+2. In Discord, right-click your bot and select "Apps" → "AeThex Activity"
+3. The Activity should open in a modal
+4. Check browser console for any errors (press `F12`)
+
+---
+
+## Debugging Checklist
+
+### Server-Side Checks
+
+#### 1. Verify Interactions Endpoint is Responding
+```bash
+# Test if endpoint is reachable
+curl -v https://aethex.dev/api/discord/interactions
+
+# Should return 401 (because we're not sending a valid Discord signature)
+# If it returns 403 or 404, there's a routing issue
+```
+
+#### 2. Check DISCORD_PUBLIC_KEY is Set
+```bash
+# On your server/hosting platform, verify:
+echo $DISCORD_PUBLIC_KEY
+# Should output a 64-character hex string
+```
+
+#### 3. Check X-Frame-Options Headers
+```bash
+# Verify the server is allowing iframe embedding
+curl -I https://aethex.dev/api/discord/interactions
+# Look for: X-Frame-Options: ALLOWALL
+# Should NOT be: X-Frame-Options: SAMEORIGIN
+```
+
+### Client-Side Checks
+
+#### 1. Open Browser Console (F12)
+- Look for `[Discord Activity]` log messages
+- They should show:
+  - `Initialization starting...`
+  - `Creating SDK with clientId: 578971245454950421`
+  - `SDK is ready`
+  - Either `Current user: exists` or `Authorizing user...`
+
+#### 2. Check frame_id Parameter
+- When inside Discord Activity, the URL should contain `?frame_id=...`
+- If no `frame_id`, Discord hasn't launched the Activity properly
+- This usually means the Activity URL is misconfigured
+
+#### 3. Check Discord SDK Loading
+- The Discord SDK should load from: `https://cdn.discordapp.com/assets/embedded/lazyload.min.js`
+- If this fails, check your CORS settings or ISP blocks
+
+---
+
+## Common Issues & Solutions
+
+### Issue 1: "Not in Discord Activity context (no frame_id)"
+**Cause:** Discord is not launching the Activity with the required parameter
+
+**Solution:**
+1. Verify Activity URL is set to: `https://aethex.dev/activity` (exactly)
+2. Wait 5 minutes for Discord to cache the configuration
+3. Try again in Discord
+
+### Issue 2: "Failed to initialize Discord Activity"
+**Cause:** Discord SDK failed to initialize or authorize
+
+**Solution:**
+1. Check browser console for specific error message
+2. Verify `VITE_DISCORD_CLIENT_ID=578971245454950421` is set
+3. Ensure `identify` scope is selected in OAuth2 settings
+4. Try opening Activity in an incognito window (clear cache)
+
+### Issue 3: "X-Frame-Options: sameorigin" Error
+**Cause:** Server is sending restrictive frame headers
+
+**Solution:**
+1. Verify `/api/discord/interactions` endpoint exists and is reachable
+2. Check that `X-Frame-Options: ALLOWALL` is being set (line 159 of code/server/index.ts)
+3. Check that `Access-Control-Allow-Origin: *` is being set
+4. Restart the server to apply header changes
+
+### Issue 4: 403 Forbidden on Directory API
+**Cause:** Discord can't validate your app configuration
+
+**Solution:**
+1. Ensure Activities feature is fully enabled
+2. Wait 10 minutes after changing any settings
+3. Clear browser cache (Ctrl+Shift+Delete)
+4. Try in a different browser
+5. Contact Discord support if issue persists
+
+---
+
+## Testing Activity in Development
+
+### Using Discord's Embedded Test
+1. Go to your app's Activity Settings
+2. Click "Test Activity" or "Preview" button
+3. Activity should open in a modal window
+4. Check console (F12) for errors
+
+### Using a Test Server
+1. Create a private Discord server
+2. Add bot to the server
+3. Right-click bot name → Apps → Select your activity
+4. Activity modal should open
+
+---
+
+## Environment Variables to Verify
+
+On your hosting platform (Vercel, Railway, etc.), ensure these are set:
+
+```
+DISCORD_BOT_TOKEN=NTc4OTcxMjQ1NDU0OTUwNDIx.Gxq1Fg.tvKSDkB7YnohZMUNJs6_Glp06_HjmL0kCcLhQ0
+DISCORD_PUBLIC_KEY=d9771dd29e3a6f030cb313e33bb4b51384c7c36829bd551df714681dcf1e1eb0
+DISCORD_CLIENT_ID=578971245454950421
+DISCORD_CLIENT_SECRET=JKlilGzcTWgfmt2wEqiHO8wpCel5VEji
+VITE_DISCORD_CLIENT_ID=578971245454950421
+```
+
+---
+
+## Still Not Working?
+
+1. **Check the logs**: Look at your hosting platform's logs for errors
+2. **Check browser console**: Press F12 and look for `[Discord Activity]` messages
+3. **Verify Discord Portal**: Screenshot your Activity Settings to confirm configuration
+4. **Test endpoint manually**: Try `curl -v https://aethex.dev/api/discord/interactions`
+5. **Clear everything**: Clear browser cache, restart bot, wait 10 minutes, try again
+
+---
+
+## Discord Developer Portal Checklist
+
+- [ ] Activities feature is enabled
+- [ ] Activity URL is set to `https://aethex.dev/activity`
+- [ ] Interactions Endpoint URL is set to `https://aethex.dev/api/discord/interactions`
+- [ ] Instance URL is set to `https://aethex.dev`
+- [ ] Client ID matches: `578971245454950421`
+- [ ] Client Secret is set and correct
+- [ ] OAuth2 scopes include `identify` and `guilds`
+- [ ] Interactions Endpoint shows green checkmark (verified)
+- [ ] You waited at least 2 minutes after saving changes