메시지 강제 변환 실패 (MESSAGE_COERCION_FAILURE)

메시지 객체가 기대하는 형식에 맞지 않을 때 발생하는 오류예요. 채팅 모델에 넘긴 입력이 "메시지로 변환(강제 변환, coercion)"될 수 없는 형태라면 이 오류가 나요. 이름 그대로 "메시지 강제 변환 실패"죠.

출처: 공식문서

허용되는 메시지 형식 (Accepted message formats)

LangChain 모듈은 MessageLikeRepresentation 형식을 받아요. 정의는 다음과 같아요.

from typing import Union

from langchain_core.prompts.chat import (
    BaseChatPromptTemplate,
    BaseMessage,
    BaseMessagePromptTemplate,
)

MessageLikeRepresentation = Union[
    Union[BaseMessagePromptTemplate, BaseMessage, BaseChatPromptTemplate],
    tuple[
        Union[str, type],
        Union[str, list[dict], list[object]],
    ],
    str,
]

여기에는 OpenAI 스타일 메시지 객체({ role: "user", content: "Hello world!" }), 튜플, 그리고 일반 문자열(내부적으로 HumanMessage 객체로 변환됨)이 모두 포함돼요.

이 형식 중 하나에 들어맞지 않는 값이 모듈로 전달되면 오류가 발생해요.

from langchain_anthropic import ChatAnthropic

uncoercible_message = {"role": "HumanMessage", "random_field": "random value"}

model = ChatAnthropic(model="claude-sonnet-4-6")

model.invoke([uncoercible_message])

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

문제 해결 (Troubleshooting)

이 오류를 해결하려면 다음을 확인해 보세요.

형식이 맞는지 확인하세요. 채팅 모델에 들어가는 모든 입력은 LangChain 메시지 클래스의 배열 또는 지원되는 메시지 형태여야 해요.
메시지에 의도하지 않은 문자열화(stringification)나 변형이 일어나지 않았는지 확인하세요.
오류의 스택 트레이스를 살펴보고, 모델에 전달하기 전에 메시지 객체를 검사하는 로깅을 추가해 보세요.