name: discord-bot-token-debug

description: Diagnose Discord bot token issues — distinguish invalid tokens from network problems

triggers:

- discord connection failed

- improper token

- discord 401 unauthorized

- discord bot not working

Discord Bot Token Debugging Skill

Diagnostic Workflow

Step 1: Verify token format

`python

parts = token.split(".")

print(f"Parts: {len(parts)}, Length: {len(token)}")

Valid Discord bot tokens: 3 parts, ~90 characters total

`

Step 2: Test gateway endpoint (NOT auth)

`bash

curl -s -H "Authorization: Bot YOUR_TOKEN" \

"https://discord.com/api/v10/gateway"

`

• - Always returns {"url":"wss://gateway.discord.gg"} even with invalid tokens
• - This endpoint does NOT validate the token

Step 3: Test REST auth (determinative)

`bash

curl -s -H "Authorization: Bot YOUR_TOKEN" \

-H "User-Agent: DiscordBot (hermes, 1.0)" \

"https://discord.com/api/v10/users/@me"

`

• - Returns 200 OK + bot info if token is valid
• - Returns 401 Unauthorized if token is invalid/revoked

Step 4: WebSocket identify (for complete diagnosis)

`python

import websockets, asyncio, json, urllib.request

async def ws_identify(token):

req = urllib.request.Request(

"https://discord.com/api/v10/gateway",

headers={"Authorization": f"Bot {token}"}

)

gateway_url = json.loads(urllib.request.urlopen(req).read().decode())["url"]

identify = {

"op": 2,

"d": {

"token": token,

"properties": {"$os": "linux", "$browser": "hermes-agent", "$device": "hermes-agent"},

"intents": 513

}

}

async with websockets.connect(f"{gateway_url}/?v=10&encoding=utf8") as ws:

await ws.send(json.dumps(identify))

msg = await asyncio.wait_for(ws.recv(), timeout=5)

data = json.loads(msg)

if data.get("op") == 10: # Hello

msg2 = await asyncio.wait_for(ws.recv(), timeout=5)

op = json.loads(msg2).get("op")

if op == 11: return "✅ Valid token"

if op == 4004: return "❌ Invalid/revoked token"

`

Key Findings

Common Causes of "Improper token" Error

1. Token was Reset on Discord Developer Portal — old token is now invalid

2. Token has leading/trailing whitespace — strip it

3. Token is truncated in .env file (e.g. MTQ4NT...4eF5)

4. Bot not yet added to any server — doesn't cause auth failure, but bot won't respond

Solution

If token is invalid:

1. Go to https://discord.com/developers/applications

2. Select your bot → Bot → Token → Reset Token

3. Update with: hermes config set DISCORD_BOT_TOKEN "NEW_TOKEN"