Skip to content
← Back to activity

Immutable solution version

ValueError: Message dict must contain 'role' and 'content' keys

Version 2Sign in to save

Complete solution

LangChain accepts message-like inputs in a few specific shapes: message objects, OpenAI-style dicts, tuples, and plain strings. Anything else raises a coercion failure. The usual cause is a hand-built dict with the wrong keys or a message that got stringified somewhere. Not for different error messages.

TL;DR: LangChain accepts message-like inputs in a few specific shapes: message objects, OpenAI-style dicts, tuples, and plain strings. Anything else raises a coercion failure. Log the messages right before the model call and check each one against the accepted shapes.

The error

ValueError: Message dict must contain 'role' and 'content' keys, got {'role': 'HumanMessage', 'random_field': 'random value'}

The fix

  1. LangChain message objects (HumanMessage, AIMessage, SystemMessage, ToolMessage)
  2. OpenAI-style dicts: {"role": "user", "content": "Hello world!"}
  3. Tuples like ("human", "Hello")
  4. Plain strings (become HumanMessage)
  5. A dict with the wrong keys. The role must be a real role ("user", "assistant", "system"), not the class name.
  6. Messages that passed through JSON serialization and came back as strings, then got wrapped again.
  7. Custom code building dicts with extra or renamed fields.
  8. Log the messages right before the model call and check each one against the accepted shapes.
  9. Normalize: convert dicts to the OpenAI-style shape with exactly role and content, or construct real message objects.
  10. Find where the transformation happens (a custom serializer, a cache layer) and fix it there, not at the call site.

When to use this

  • You are seeing this exact error message; match the block above, not just part of it.
  • The failing call matches the scenario in the title: ValueError.
  • You want the fastest verified fix before digging through logs.

When not to use this

  • Your error text differs from the block above; close cousins often have different causes.
  • The stack trace points at a different component than the one in the title.
  • You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

  • Not pinned to a specific version; follows current ValueError behavior.

Evidence

Error catalog entry grounded in the official MESSAGECOERCIONFAILURE error page, verified 2026-09-26. Error page: https://docs.langchain.com/oss/python/langchain/errors/MESSAGECOERCIONFAILURE

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_ugJ1GwlyMCsnKvv1X73pMg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">ValueError: Message dict must contain &#39;role&#39; and &#39;content&#39; keys <span>— Vectle</span></a>