Fix: Hermes Agent Discord 'invalid literal for int()' Error

You’ve gotten past inviting the bot and enabling Privileged Gateway Intents — the gateway connects, the bot shows online — but it still doesn’t respond, or the gateway won’t even start cleanly. Two specific config mistakes cause most of what’s left, and both show up as very literal error messages once you know what to look for.

Issue 1: “invalid literal for int() with base 10”

Symptom: The gateway process crashes or logs a Python traceback ending in something like:

ValueError: invalid literal for int() with base 10: 'https://discord.com/channels/111111111111111111/222222222222222222'

Cause: Discord’s right-click menu on a channel offers Copy Link, which gives you the full URL — https://discord.com/channels/<SERVER_ID>/<CHANNEL_ID>. Hermes’s channel-related settings (DISCORD_ALLOWED_CHANNELS, DISCORD_FREE_RESPONSE_CHANNELS, DISCORD_HOME_CHANNEL) expect only the bare numeric channel ID — they get parsed directly as integers, so anything else (a URL, slashes, the server ID) fails immediately.

Fix: Find where the full URL got saved:

grep -RniF 'discord.com/channels/' ~/.hermes

That’ll point you at ~/.hermes/.env and/or ~/.hermes/config.yaml. Open whichever file it flags and replace the full URL with just the trailing number — the second ID in the URL, not the first:

# Wrong:
DISCORD_ALLOWED_CHANNELS=https://discord.com/channels/111111111111111111/222222222222222222

# Right:
DISCORD_ALLOWED_CHANNELS=222222222222222222

Do the same for DISCORD_FREE_RESPONSE_CHANNELS and DISCORD_HOME_CHANNEL if either has the same problem.

Issue 2: No User Allowlist Configured

Symptom: The gateway logs the exact warning below — the bot connects fine, but every message is treated as unauthorized regardless of who sends it:

WARNING gateway.run: No env user allowlists configured. Messaging platforms
default to pairing/allowlist policies and will deny unknown senders unless
you configure platform allowlists (e.g., TELEGRAM_ALLOWED_USERS=your_id) or
explicitly opt in with GATEWAY_ALLOW_ALL_USERS=true plus dm_policy/group_policy: open on the platform.

Note this warning is generic across every messaging platform Hermes supports, not Discord-specific — the example variable it prints (TELEGRAM_ALLOWED_USERS) will differ depending on which platform triggered it; for Discord it’s DISCORD_ALLOWED_USERS.

Cause: DISCORD_ALLOWED_USERS (or DISCORD_ALLOWED_ROLES) was never set. A connected bot and an authorized user are two independent checks — being online doesn’t imply anyone is allowed to talk to it.

Fix: Get your numeric Discord User ID, then add it:

nano ~/.hermes/.env

DISCORD_ALLOWED_USERS=YOUR_NUMERIC_USER_ID

Save and restart the gateway, then verify the values landed correctly without echoing the token itself:

grep -E '^DISCORD_(ALLOWED_USERS|ALLOWED_CHANNELS|FREE_RESPONSE_CHANNELS|HOME_CHANNEL)=' ~/.hermes/.env

Finding Your Numeric User ID (Not Your Username)

The single most common mixup here: your Discord username or tag (something like yourname_0142) is not the ID Hermes needs. You need the numeric snowflake ID, which looks like 333333333333333333.

On Discord for the web (this is the one that trips people up, since the menu layout differs slightly from desktop):

1. Click the gear icon (User Settings) in the bottom-left corner.
2. Go to Advanced.
3. Toggle on Developer Mode.
4. Go back to any channel or DM where you’ve sent a message.
5. Right-click your own name or avatar.
6. Select Copy User ID.

You’ll get a long number, not your display name. Paste that number — and only that number — into DISCORD_ALLOWED_USERS.

Issue 3: Rate-Limited After Repeated Restarts

Symptom: After fixing the two issues above, the gateway connects but a new warning shows up, specifically about thread creation:

WARNING hermes_plugins.discord_platform.adapter: [Discord] Auto-thread creation
failed after retry. Direct error: Too many requests. Retry in 276.71 seconds..
Fallback error: Too many requests. Retry in 276.29 seconds.

Cause: This isn’t a config problem — it’s Discord itself. Every crash-and-restart cycle while debugging the earlier issues is another login attempt against Discord’s API, and enough of them in a short window trips Discord’s own rate limiting, independent of anything Hermes does wrong.

Fix: Do nothing for the number of seconds Discord specifies (it counts down from when the limit was hit), then restart once and leave it alone rather than restarting repeatedly to “test” — each additional attempt while still rate-limited just resets the wait. Once it clears, a single hello in the channel is enough to confirm the bot is actually responding.

Verifying the Fix

Restart however you’re running the gateway (foreground process, or whatever supervisor — systemd or otherwise — you’ve set up to keep it alive), then check the logs for the specific problems being gone rather than just generic activity:

grep -Ei 'invalid literal for int|no.*allowlist' <your gateway log source>

No more invalid literal for int(), and no more warnings about a missing allowlist. Then test it directly: send a plain message in the channel, or mention the bot by its handle, and confirm you get a reply.

Related Articles

• Connecting Hermes Agent to GitHub: Auth Setup and Gotchas
• What is Hermes Cloud? Running Hermes Agent Without a Server
• Connecting Hermes Agent to Discord: Complete Setup Guide
• Hermes Agent Discord Bot Not Showing Up or Not Responding
• Hermes Agent on a 1GB VPS: Fixing the Common Gotchas
• What is Hermes Agent? Nous Research’s Self-Improving AI Agent