iflytek/astron-agent · error · RequestValidationError

'role' must be user or assistant

Error message

'role' must be user or assistant

What it means

The same validate_messages_params validator rejects any message whose `role` equals "system" (or otherwise outside user/assistant), raising RequestValidationError with loc body.messages[i].role and msg "'role' must be user or assistant". The agent's OpenAI-compatible input layer supports only user/assistant roles in this message array.

Solutions

1. Remove system messages from the array; move the instruction into the first user message content.
2. Use the platform's dedicated system-prompt/agent-config field instead of the messages array if available.
3. Client-side, filter or map role 'system' messages before calling the endpoint.
4. Read loc body.messages[i].role in the validation error to find the offending message.

Example fix

# before
messages = [
  {"role": "system", "content": "You are helpful."},
  {"role": "user", "content": "Hi"},
]

# after
messages = [{"role": "user", "content": "You are helpful.\nHi"}]

def strip_system(messages):
    return [m for m in messages if m.get("role") in ("user", "assistant")]

def role_is_allowed(m: dict) -> bool:
    return m.get("role") in ("user", "assistant")

try:
    r = client.post(url, json=payload)
    r.raise_for_status()
except httpx.HTTPStatusError as e:
    if e.response.status_code == 422:
        # find loc ending in ('role',) and move system content into a user message
        ...

When it happens

Trigger: Sending a request whose messages contain {"role":"system", ...} — e.g. porting a raw OpenAI request that uses a system prompt, or a client that prepends an instruction message with role system.

Common situations: Reusing prompts from plain OpenAI integrations that start with a system message; prompt templates exporting a system entry; middleware that injects system instructions into the messages array.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• 'content' cannot be empty
• messages role order must alternate between user and…
• app_name must not been empty
• cloud_id must not been empty
• dev_id must been more than zero

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/e3891d7fdf49fdcd. Report an issue: GitHub.

Appendix: source

Thrown at core/agent/api/schemas/base_inputs.py:55

        for i, message in enumerate(messages):
            if not isinstance(message, dict):
                return values

            if not message.get("content"):
                # Content cannot be empty
                raise RequestValidationError(
                    errors=[
                        {
                            "type": "literal_error",
                            "loc": ("body", "messages", i, "content"),
                            "msg": "'content' cannot be empty",
                        }
                    ]
                )

            if message.get("role") == "system":
                # System role not supported
                raise RequestValidationError(
                    errors=[
                        {
                            "type": "literal_error",
                            "loc": ("body", "messages", i, "role"),
                            "msg": "'role' must be user or assistant",
                        }
                    ]
                )

            if message.get("role") != next_role:
                # Wrong order
                raise RequestValidationError(
                    errors=[
                        {
                            "type": "literal_error",
                            "loc": ("body", "messages", i, "role"),
                            "msg": (
                                "messages role order must alternate "

View on GitHub (pinned to 5e758547a8)