Common errors

400 error with new components (Container, Text Display…)

Cause: the IS_COMPONENTS_V2 flag is missing, so Discord treats the message as legacy, where only Action Rows are allowed at the top level.

Fix: add "flags": 32768 to the message (or add it to the flags you already use).

400 error when sending `content` or `embeds`

Cause: with the V2 flag, content, embeds, sticker_ids and poll aren’t allowed.

Fix: move the text into a Text Display and the embed into a Container. See Migrating from embeds.

My attached images don’t show up

Cause: in V2 messages, attachments aren’t shown on their own.

Fix: display them with a File, Thumbnail or Media Gallery pointing to attachment://exact-name.png. The name must match the uploaded file exactly.

The webhook ignores my components

Cause: webhooks need an extra parameter.

Fix: add ?with_components=true to the webhook URL.

“This interaction failed”

Cause: your bot didn’t respond within 3 seconds, or your code threw an error before responding.

Fix:

Respond quickly. If you’ll take longer, use DEFERRED_UPDATE_MESSAGE (6) or DEFERRED_CHANNEL_MESSAGE_WITH_SOURCE (5) first.
Check your bot’s logs for exceptions.
In discord.py, make sure the view hasn’t timed out (timeout).

Validation error in `components`

Check these typical cases:

Typical error	Fix
More than 40 components	Reduce components or split into several messages.
Section without `accessory`	Add a Thumbnail or Button, or use a standalone Text Display.
Section with more than 3 texts	Merge texts into one Text Display with line breaks (`\n`).
Container inside a Container	Can’t nest: place them one after another.
Buttons and a select in the same Action Row	Use two Action Rows.
Repeated `custom_id`	Each `custom_id` must be unique in the message.
Standalone Thumbnail in the message	It can only be a Section’s `accessory`.
File with an `https://` URL	File only accepts `attachment://`. Use a Media Gallery for image URLs.
`accent_color` as a string `"#5865F2"`	Must be a number: `5793266` or `0x5865F2`.
Link button with `custom_id`	Link buttons use `url` and have no `custom_id`.

Cause	Fix
You already responded to the interaction	The modal must be the first response. Don’t `defer` before it.
Responding to a `MODAL_SUBMIT` with another modal	Not allowed. Respond with a message.
`disabled` on a select inside a modal	`disabled` only works in messages; remove it.
`min_values: 0` with `required: true`	If it’s required, `min_values` must be at least `1`.
More than 5 components in the modal	The max is 5 (Label or Text Display).

I can’t remove the V2 flag when editing

This is intentional: once a message is V2, it’s always V2. If you need a legacy message, send a new one.