{"record":{"id":"e3891d7fdf49fdcd","repo":"iflytek/astron-agent","slug":"role-must-be-user-or-assistant","errorCode":null,"errorMessage":"'role' must be user or assistant","messagePattern":"'role' must be user or assistant","errorType":"validation","errorClass":"RequestValidationError","httpStatus":422,"severity":"error","filePath":"core/agent/api/schemas/base_inputs.py","lineNumber":55,"sourceCode":"        for i, message in enumerate(messages):\n            if not isinstance(message, dict):\n                return values\n\n            if not message.get(\"content\"):\n                # Content cannot be empty\n                raise RequestValidationError(\n                    errors=[\n                        {\n                            \"type\": \"literal_error\",\n                            \"loc\": (\"body\", \"messages\", i, \"content\"),\n                            \"msg\": \"'content' cannot be empty\",\n                        }\n                    ]\n                )\n\n            if message.get(\"role\") == \"system\":\n                # System role not supported\n                raise RequestValidationError(\n                    errors=[\n                        {\n                            \"type\": \"literal_error\",\n                            \"loc\": (\"body\", \"messages\", i, \"role\"),\n                            \"msg\": \"'role' must be user or assistant\",\n                        }\n                    ]\n                )\n\n            if message.get(\"role\") != next_role:\n                # Wrong order\n                raise RequestValidationError(\n                    errors=[\n                        {\n                            \"type\": \"literal_error\",\n                            \"loc\": (\"body\", \"messages\", i, \"role\"),\n                            \"msg\": (\n                                \"messages role order must alternate \"","sourceCodeStart":37,"sourceCodeEnd":73,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/agent/api/schemas/base_inputs.py#L37-L73","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove system messages from the array; move the instruction into the first user message content.","Use the platform's dedicated system-prompt/agent-config field instead of the messages array if available.","Client-side, filter or map role 'system' messages before calling the endpoint.","Read loc body.messages[i].role in the validation error to find the offending message."],"exampleFix":"# before\nmessages = [\n  {\"role\": \"system\", \"content\": \"You are helpful.\"},\n  {\"role\": \"user\", \"content\": \"Hi\"},\n]\n\n# after\nmessages = [{\"role\": \"user\", \"content\": \"You are helpful.\\nHi\"}]","handlingStrategy":"validation","validationCode":"def strip_system(messages):\n    return [m for m in messages if m.get(\"role\") in (\"user\", \"assistant\")]","typeGuard":"def role_is_allowed(m: dict) -> bool:\n    return m.get(\"role\") in (\"user\", \"assistant\")","tryCatchPattern":"try:\n    r = client.post(url, json=payload)\n    r.raise_for_status()\nexcept httpx.HTTPStatusError as e:\n    if e.response.status_code == 422:\n        # find loc ending in ('role',) and move system content into a user message\n        ...","preventionTips":["Keep system prompts in the platform's system-prompt config, not the messages array.","Filter/migrate role 'system' entries when porting prompts from raw OpenAI integrations.","Run a client-side schema check restricting roles to user/assistant.","Document the supported roles in your API client wrapper."],"tags":["api","validation","openai-compatible","fastapi"],"backgroundTag":"invalid-enum-value","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}