fix: improve gateway intents and auth error messages

[masami-agent]

Summary

Closes #116

Catch DisallowedGatewayIntents and InvalidAuthentication errors from the Discord gateway with actionable error messages instead of cryptic serenity errors that cause CrashLoopBackOff with no guidance.

Changes

File	Change
src/main.rs	Replace bare client.start().await? with match block catching DisallowedGatewayIntents and InvalidAuthentication
README.md	Add prerequisites section documenting required Discord Developer Portal settings

Error messages

DisallowedGatewayIntents:

Discord rejected privileged intents. Enable MESSAGE CONTENT INTENT at: https://discord.com/developers/applications → Bot → Privileged Gateway Intents

InvalidAuthentication:

Discord rejected bot token. Verify your bot_token in config.toml is correct and has not been reset.

What is NOT changed

Per discussion in #116:

• Intents are not made configurable in config.toml — openab requires MESSAGE_CONTENT to function
• Only the two most common DX footguns are caught — not every possible serenity error

Testing

• Verified serenity::Error::Gateway(GatewayError::DisallowedGatewayIntents) and GatewayError::InvalidAuthentication exist in serenity 0.12.5
• Issue confirmed reproducible on 0.7.2-beta.3 (see Hardcoded privileged gateway intents cause CrashLoopBackOff with no actionable error message #116 comment)

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: fix: improve gateway intents and auth error messages
• Source: fix: improve gateway intents and auth error messages #328
• Status: screened from label pending-screening
• Generated at: 2026-04-21T17:29:42.389Z
• Discord thread: https://discord.com/channels/1488041051187974246/1496201113358307530

Screening report

## Intent

This PR is trying to make OpenAB fail clearly when Discord startup is misconfigured, instead of crashing with low-signal Serenity errors. The concrete operator-visible problem is that a bad bot token or missing privileged gateway intents currently leads to a startup failure that looks opaque enough to cause wasted debugging time and, in containerized deploys, repeated CrashLoopBackOff without guidance.

Feat

This is primarily a fix with a small docs improvement.

Behaviorally, it changes Discord gateway startup so two common failure modes are translated into actionable messages:

• missing required privileged intents
• invalid bot authentication token

It also updates the README to document the required Discord Developer Portal settings.

Who It Serves

The primary beneficiary is deployers and maintainers running the Discord gateway, especially anyone standing up OpenAB for the first time or recovering from broken credentials.

Secondarily, it helps reviewers and support operators because the failure mode becomes self-diagnosing.

Rewritten Prompt

Update the Discord startup path to catch serenity gateway errors for DisallowedGatewayIntents and InvalidAuthentication and return operator-facing messages that explain exactly what to fix. Add a short README prerequisites section covering the required Discord Developer Portal privileged intent setting and token validation expectations. Keep the scope narrow: do not add intent configurability, and do not attempt broad error remapping beyond these two cases. Verify the bot exits with the improved messages for each mapped failure and preserves existing behavior for all other startup errors.

Merge Pitch

This is a high-value, low-risk DX fix. It addresses a real startup footgun in the Discord integration and reduces wasted operator time without changing runtime behavior in healthy deployments.

The likely reviewer concern is scope creep: whether this should become a broader startup-error framework or configurable intents work. The PR avoids that by targeting only the two highest-frequency misconfigurations and documenting the required setup.

Best-Practice Comparison

Relevant OpenClaw principles:

• explicit delivery/runtime routing: partially relevant, because this is about surfacing gateway-specific startup failures at the correct boundary
• retry/backoff and run logs: somewhat relevant, because clear logs are part of operability, though this PR does not add retry policy or durable run history
• gateway-owned scheduling, durable job persistence, isolated executions: not relevant to this item

Relevant Hermes Agent principles:

• self-contained prompts for scheduled tasks: not relevant
• file locking, atomic writes, fresh session per scheduled run: not relevant
• daemon/operator safety principles are indirectly relevant only in the sense that failures should be explicit and actionable

Net: this PR aligns with operational best practice on observability and operator guidance, but it is not a scheduler, persistence, or isolation change. The right comparison is not architecture depth; it is whether OpenAB surfaces actionable failure reasons at the gateway boundary. On that axis, this change is directionally correct.

Implementation Options

1. Conservative option: targeted error mapping
   Catch only DisallowedGatewayIntents and InvalidAuthentication where client.start().await is called, emit precise messages, and leave all other errors unchanged. Add matching README prerequisites.

2. Balanced option: startup error classification helper
   Introduce a small helper function that classifies known startup errors into operator-facing messages, including the two current cases and a clean fallback path. Keep the same external behavior, but centralize the mapping so future startup diagnostics are easier to extend.

3. Ambitious option: structured startup diagnostics layer
   Create a broader startup diagnostics path for gateway boot failures with typed categories, normalized logging, and remediation hints for multiple common Discord misconfigurations. Pair it with clearer exit semantics and possibly test fixtures around startup failure reporting.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative targeted mapping	Fast	Low	Good for the two known cases	Acceptable	High for affected deployers	Strong
Balanced helper-based classification	Medium	Low-medium	Good and easier to extend safely	Good	High	Strong
Ambitious diagnostics layer	Slow	Medium-high	Potentially best long-term	Good if fully carried through	High eventually	Weak-medium

Recommendation

Recommend the balanced path if the code stays small; otherwise accept the conservative version as-is.

The core reason is that the problem is real and narrow, and OpenAB benefits immediately from clearer startup diagnostics. A tiny classification helper gives the next maintainer a cleaner place to add future Discord boot errors without turning this PR into an architecture project. If review pressure is to minimize surface area, merge the conservative form now and split any broader startup diagnostics work into a follow-up issue.

[masami-agent]

@masami-agent This PR has merge conflicts and is marked closing-soon. Please rebase onto main and force push to resolve. The fix itself looks good — just needs a fresh rebase.

git fetch upstream main
git rebase upstream/main
# resolve conflicts in src/main.rs
git push --force-with-lease

[github-actions]

⚠️ This PR is missing a Discord Discussion URL in the body.

All PRs must reference a prior Discord discussion to ensure community alignment before implementation.

Please edit the PR description to include a link like:

Discord Discussion URL: https://discord.com/channels/...

This PR will be automatically closed in 3 days if the link is not added.

[masami-agent]

Rebased onto current main and force-pushed (5d62c7a → 21b7f5d).

Conflicts resolved:

• src/main.rs — added use serenity::gateway::GatewayError import alongside existing imports; placed the match block at the correct location (line 340, inside the if let Some(discord_cfg) block where client.start().await? was)
• README.md — added Prerequisites section above the updated "1. Create a Bot" heading, updated doc link to docs/discord.md

The diff is minimal: +1 import line, +18 lines for the match block in main.rs, +13 lines for Prerequisites in README.md. All surrounding code (multi-adapter support, Slack, Gateway, cron, shutdown logic) is untouched.

[obrutjack]

Rebased, CI green (all 7 smoke tests pass). Clean fix — catches DisallowedGatewayIntents and InvalidAuthentication with actionable error messages. README prerequisites section is a good addition. LGTM.

[chaodu-agent]

LGTM ✅ — Clean, minimal fix for a real DX footgun. One non-blocking NIT below.

四問框架 Analysis

1. What problem does it solve?

Bare client.start().await? propagates cryptic serenity errors when Discord rejects privileged intents or an invalid bot token. Operators see Error: Disallowed gateway intents were provided with no guidance, leading to CrashLoopBackOff and wasted debugging time. Issue #116 documents this.

2. How does it solve it?

Wraps client.start().await in a match block that catches two specific GatewayError variants:

• DisallowedGatewayIntents → actionable message with Developer Portal URL
• InvalidAuthentication → actionable message pointing to config.toml

README gains a Prerequisites section documenting the required Developer Portal settings.

3. What was considered?

Per #116 discussion: making intents configurable was considered and explicitly deferred — openab requires MESSAGE_CONTENT to function. Only the two most common DX footguns are caught, not every possible serenity error. This is the right scope.

4. Is this the best approach?

Yes for the scope. The match patterns are correct for serenity 0.12.5. Error messages are actionable and include direct URLs. README addition is well-placed before the Quick Start steps.

Traffic Light

🟢 INFO — Correct GatewayError variant matching confirmed against serenity 0.12.5 source. Both DisallowedGatewayIntents and InvalidAuthentication are real enum variants in serenity::gateway::GatewayError.

🟢 INFO — README Prerequisites section references existing docs/discord.md which is confirmed to exist on main.

🟢 INFO — Minimal diff (+20/-1 in main.rs, +13 in README). No unnecessary changes.

🟡 NIT — std::process::exit(1) bypasses the cleanup block below the match:

// Cleanup
cleanup_handle.abort();
let _ = shutdown_tx.send(true);
// ... slack/gateway/cron handle joins

Since these errors occur at startup (before any sessions or adapters are active), the cleanup is effectively a no-op — so exit(1) is safe in practice. However, return Err(anyhow!("Discord rejected privileged intents...")) would be more idiomatic Rust and future-proof if cleanup logic grows. Non-blocking — the current approach works correctly.

Baseline Check (Step 0)

• Main branch: bare client.start().await? at line 339 of src/main.rs
• serenity 0.12.5 confirmed in Cargo.lock
• No existing error handling for gateway connection failures
• README has no prerequisites section — PR adds net-new content
• docs/discord.md exists on main (referenced in new README section)

Review by 超渡法師 · Four-monk collaborative triage in progress