{"record":{"id":"9d9a31c17e7fda27","repo":"zylon-ai/private-gpt","slug":"system-messages-should-be-as-layer-in-the-context","errorCode":null,"errorMessage":"System messages should be as layer in the context stack.","messagePattern":"System messages should be as layer in the context stack\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"private_gpt/server/chat/interceptors/validator_request_interceptor.py","lineNumber":128,"sourceCode":"        tokenize = context.state.runtime.tokenizer_fn\n        if token_limit is None or tokenize is None:\n            return\n\n        user_message_tokens = len(\n            await async_tokenizer(texts=user_text, tokenizer_fn=tokenize)\n        )\n        if user_message_tokens > token_limit:\n            raise Errors.RequestTooLarge(\n                f\"The message length {user_message_tokens} exceeds the maximum token limit {token_limit}.\",\n                Errors.Codes.REQUEST_TOO_LARGE_USER_MSG,\n            )\n\n        # If a system message is present in the request messages, it's a misuse\n        potential_system_message = self._system_message_text(\n            context.state.input.request.messages\n        )\n        if potential_system_message:\n            raise RuntimeError(\n                \"System messages should be as layer in the context stack.\"\n            )\n\n        # Prefer system prompt from the context stack, fall back to prompt\n        system_prompt_block = (\n            context.state.input.context_stack.to_system_prompt()\n            or request.system.get_prompt()\n            or None\n        )\n        system_prompt = (\n            \"\\n\".join(\n                [block.text for block in system_prompt_block]\n                if system_prompt_block\n                else []\n            )\n            if system_prompt_block\n            else None\n        )","sourceCodeStart":110,"sourceCodeEnd":146,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/server/chat/interceptors/validator_request_interceptor.py#L110-L146","documentation":"A plain RuntimeError raised when a message with role=system is found inside request.messages. The architecture requires system prompts to be supplied as a context-stack layer (context.state.input.context_stack.to_system_prompt()) or via request.system.get_prompt(), never as an inline system message. Hitting it means the caller is using the API incorrectly.","triggerScenarios":"POSTing a messages array that contains {\"role\": \"system\", \"content\": ...} with non-empty text; porting OpenAI-style request payloads unchanged into this server.","commonSituations":"Migrating an OpenAI client integration that prepends a system message; SDK examples copied from generic chat APIs; agents/frameworks (LangChain, autogen) that auto-inject system roles into messages.","solutions":["Remove the system message from request.messages and pass the prompt via the context stack (system prompt layer) or the request.system field.","If using an OpenAI-compatible facade, filter out system-role messages before forwarding.","If you intended the text as instructions, move it into the dedicated system prompt configuration."],"exampleFix":"# before\nmessages = [ChatMessage(role=MessageRole.SYSTEM, ...), ChatMessage(role=MessageRole.USER, ...)]\n\n# after\nmessages = [ChatMessage(role=MessageRole.USER, ...)]\nrequest = ChatRequest(messages=messages, system=SystemPrompt(prompt=\"You are a helpful assistant\"))","handlingStrategy":"validation","validationCode":"assert not any(m.role == MessageRole.SYSTEM for m in request.messages), 'system role not allowed in messages'","typeGuard":"def has_inline_system_message(messages: list[ChatMessage]) -> bool:\n    return any(m.role == MessageRole.SYSTEM for m in messages)","tryCatchPattern":null,"preventionTips":["Never port OpenAI payloads verbatim; strip system roles first","Put instructions in request.system or the context stack","Add a client-side lint that rejects system-role messages"],"tags":["validation","system-prompt","misuse","chat"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}