Slack error invalid_blocks: Blocks are not valid

Your blocks array parsed as JSON but failed Block Kit validation. The documented description — "Blocks submitted with this message are not valid" — is famously unspecific, which makes this one of the most time-consuming Slack errors per incident: a 40-block payload fails, and the string tells you neither which block nor which field. The first move is always the same: log the entire response body, because Slack frequently attaches a response_metadata object whose messages array contains human-readable pointers to the failing block index and field. Code that logs only error discards the only map you get.

The validation rules being violated are almost always documented limits or type mistakes. The budget rules from the Block Kit reference: "You can include up to 50 blocks in each message, and 100 blocks in modals or Home tabs." Per block: a section block's text has a 3,000-character maximum; section fields allow at most 10 items of 2,000 characters each; a header block's text caps at 150 characters; a context block holds at most 10 elements; an actions block at most 25; block_id caps at 255 characters everywhere. Type mistakes are the other half: plain_text supplied where mrkdwn is required (or vice versa), a string where an object belongs, an element placed in a block that does not accept it, or an emoji/URL field that fails format checks.

Dynamic data is the underlying villain. Handwritten blocks fail in development and get fixed; production failures come from templates inflated by real content — a customer name pushing a header past 150 characters, a description pushing section text past 3,000, a loop emitting 60 blocks for a long list. That is why this error correlates with specific records rather than with deploys.

Distinguish the sibling invalid_blocks_format: that one means the blocks value was not even a valid JSON array of objects (typically a double-serialized string), failing before Block Kit rules are consulted. invalid_blocks means the JSON was fine and the content broke the rules. Validate candidate payloads interactively in Slack's Block Kit Builder, which highlights the failing property, and see the full budget table in Slack Block Kit limits.

{
  "ok": false,
  "error": "invalid_blocks",
  "response_metadata": { "messages": [ "...pointer to the failing block..." ] }
}

Build blocks through a typed builder or schema validation layer that enforces the documented budgets at construction time, so oversized content is truncated deliberately instead of rejected at send time. Test templates with worst-case data lengths. Keep the Block Kit limits table next to your message builders, and treat any block assembled by string concatenation as a bug waiting for a long customer name.