Discord adapter drops guild messages from unregistered channels: `await` before forwarding lets discord.js make the raw packet circular

[BuckG71]

Summary

In @chat-adapter/discord@4.38.1, a guild MESSAGE_CREATE arriving from a
channel that is not already in respondToChannelIds is silently discarded.
forwardGatewayEvent calls JSON.stringify(event) with no replacer, and by the
time it runs the raw packet has become circular, so the stringify throws, the
catch logs, and the event never reaches the webhook.

The failure is specific and unfortunate: the only code path that can discover a
new channel is the one that breaks. Channels already registered keep working, so
an existing deployment looks healthy while onboarding any new channel is
impossible. Nothing surfaces to the operator except a log line.

This is a regression from 4.29.0, which forwards the same packet without
incident.

Root cause

runGatewayListener registers a raw handler. In 4.29.0 it forwards
immediately:

client.on("raw", async (packet) => {
  if (isShuttingDown) return;
  if (!packet.t) return;
  this.logger.info("Discord Gateway forwarding event", { type: packet.t });
  await this.forwardGatewayEvent(webhookUrl, {
    type: `GATEWAY_${packet.t}`,
    timestamp: Date.now(),
    data: packet.d,
  });
});

The handler runs synchronously up to the fetch inside forwardGatewayEvent, so
JSON.stringify sees the packet exactly as it came off the wire.

4.38.1 inserts a thread-detection block before the forward:

let data = packet.d;
if (packet.t === "MESSAGE_CREATE" && this.respondToChannelIds.length > 0) {
  const message = packet.d;
  if (!(message.author.bot || this.respondToChannelIds.includes(message.channel_id))) {
    const channel = await client.channels.fetch(message.channel_id).catch(...);
    //              ^^^^^ yields the event loop
    if (channel?.isThread() && ...) { data = { ...message, thread: {...} }; }
  }
}
await this.forwardGatewayEvent(webhookUrl, { type: `GATEWAY_${packet.t}`, timestamp: Date.now(), data });

await client.channels.fetch(...) yields control. discord.js's own
MESSAGE_CREATE action handler then runs against the same object and, while
constructing the GuildMember, sets packet.d.member.user. That back-reference
makes the packet circular. When forwardGatewayEvent finally serializes it:

body: JSON.stringify(event)   // throws

[chat-sdk:discord] Error forwarding Gateway event {
  type: 'GATEWAY_MESSAGE_CREATE',
  error: 'TypeError: Converting circular structure to JSON
    --> starting at object with constructor 'Object'
    |     property 'member' -> object with constructor 'Object'
    --- property 'user' closes the circle'
}

The guard conditions explain the observed blast radius exactly:

• DMs carry no member, so they never become circular. Unaffected.
• Registered guild channels short-circuit on
  respondToChannelIds.includes(message.channel_id), skip the await, and
  forward before discord.js can mutate anything. Unaffected.
• Unregistered guild channels take the await. Always dropped.

Reproduction

1. Run the adapter in gateway-forwarding mode with a non-empty
   respondToChannelIds that does not include some channel C.
2. Post a message in C from a non-bot account.
3. Observe Discord Gateway forwarding event { type: 'MESSAGE_CREATE' } with no
   corresponding forwarded Gateway event received, and the circular-structure
   error above.

Impact

Any deployment that registers channels by observing a first message cannot
onboard a new channel at all. In our case a newly created Discord channel was
invisible to the router across two attempts, with no error anywhere the operator
would look — only in the adapter's own error log.

Suggested fixes

Either would do; the second is closer to the pre-4.38.1 contract.

1. Serialize cycle-safely. Minimal, and because the mutation discord.js adds
is exactly member.user (which duplicates author, and which Discord does not
send on the wire), dropping the cycle restores the original payload shape:

const ancestors = [];
const body = JSON.stringify(event, function (key, value) {
  if (typeof value !== "object" || value === null) return value;
  while (ancestors.length > 0 && ancestors[ancestors.length - 1] !== this) ancestors.pop();
  if (ancestors.includes(value)) return void 0;
  ancestors.push(value);
  return value;
});

Note this must track the ancestor path, not a WeakSet of everything seen — a
WeakSet also drops legitimate repeated references, e.g. a self-mention where
mentions[0] and author are the same object.

2. Snapshot the packet before yielding. Take a structured clone of packet.d
at the top of the raw handler and use that throughout, so the forwarded payload
is the wire packet regardless of what discord.js does to its copy afterwards.

Environment

• @chat-adapter/discord 4.38.1 (regression from 4.29.0)
• Still present in 4.40.0, latest as of 2026-09-05 — verified against the
  published tarball: forwardGatewayEvent is unchanged and
  body: JSON.stringify(event) is still unguarded at dist/index.js:2650.
• chat 4.38.1
• Node 24.14.0, macOS 26 arm64
• Gateway-forwarding mode with a webhook URL

Workaround

Patched locally via pnpm patch using fix 1 above. Verified: guild messages from
an unregistered channel now forward and the channel registers correctly, with no
change in behaviour for DMs or already-registered channels.

[amitvijapur]

I'd like to take this one if nobody else has started.

Working on the snapshot approach (your option 2) rather than the cycle-safe replacer, since it restores the pre-4.38.1 contract of forwarding the wire packet rather than whatever discord.js has since mutated, and it does not depend on the mutation staying exactly member.user. Will verify against current main first and confirm the reproduction before opening anything.

[amitvijapur]

I have a fix working, but before I open it I want to flag that I could not reproduce the circular-structure throw, and I think the root cause here is slightly off. Happy to be shown wrong.

The mutation is real. Against discord.js@14.25.1 (what ^14.25.1 currently resolves to), src/structures/Message.js:342:

this.guild.members._add(Object.assign(data.member, { user: this.author }));

Object.assign writes into the caller's data.member, so the raw packet really is patched in place while our handler is parked. That part matches your analysis exactly.

But that assignment does not close a cycle. this.author is a discord.js User, not a back-reference into d. User inherits toJSON from Base, and Base's constructor defines client with Object.defineProperty(this, 'client', { value: client }), so it is non-enumerable. JSON.stringify calls toJSON() and gets a flat object. I tested it with a deliberately self-referential client and it still serialized:

{"channel_id":"c1","author":{...},"member":{"user":{"id":"u1","username":"bob"}}}

A shared reference is not a cycle. d.member.user = d.author on plain objects serializes by duplication rather than throwing. For JSON.stringify to throw you need a genuine back-edge, something like d.author.member = d.member, and I could not find a path in 14.25.1 that creates one. CachedManager._add, GuildMember._patch and ChannelManager._add all read from data without writing references back into it.

So what is your discord.js version? The adapter declares ^14.25.1, so a deployment can be on a different 14.x than this one. Your stack trace is real and I would like to find what produces it. If you still have it, the full circular path from the error would help.

One correction that strengthens your report. You scope the blast radius to unregistered channels because registered ones "skip the await". They don't. forwardGatewayEvent awaits resolveBotToken() before the JSON.stringify, on every path, and botToken is documented as accepting an async resolver. discord.js also emits raw and calls handlePacket in the same synchronous turn, so our handler suspends at its first await and hands control straight back. Any await is enough, no I/O needed, and every forwarded event is exposed rather than only the fetch path.

The fix is worth landing either way. Snapshotting packet.d before the first await means the webhook gets the wire packet instead of whatever discord.js has since written into it. Today that shows up as a member.user field Discord never sent. If a version does produce a cycle, the same snapshot prevents it, since the clone runs before any mutation can land. I have it passing with a regression test and will open it framed as payload integrity rather than a dropped message, unless you would rather I hold until we pin down the throw.

Disclosure: written with AI assistance, reviewed by me before posting.