{"record":{"id":"f499e02bd2906a4c","repo":"run-llama/llama_index","slug":"cannot-specify-both-system-prompt-and-prefix-messa-f499e0","errorCode":null,"errorMessage":"Cannot specify both system_prompt and prefix_messages","messagePattern":"Cannot specify both system_prompt and prefix_messages","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/chat_engine/simple.py","lineNumber":58,"sourceCode":"        chat_history: Optional[List[ChatMessage]] = None,\n        memory: Optional[BaseMemory] = None,\n        memory_cls: Type[BaseMemory] = Memory,\n        system_prompt: Optional[str] = None,\n        prefix_messages: Optional[List[ChatMessage]] = None,\n        llm: Optional[LLM] = None,\n        **kwargs: Any,\n    ) -> \"SimpleChatEngine\":\n        \"\"\"Initialize a SimpleChatEngine from default parameters.\"\"\"\n        llm = llm or Settings.llm\n\n        chat_history = chat_history or []\n        memory = memory or memory_cls.from_defaults(\n            chat_history=chat_history, token_limit=llm.metadata.context_window - 256\n        )\n\n        if system_prompt is not None:\n            if prefix_messages is not None:\n                raise ValueError(\n                    \"Cannot specify both system_prompt and prefix_messages\"\n                )\n            prefix_messages = [\n                ChatMessage(content=system_prompt, role=llm.metadata.system_role)\n            ]\n\n        prefix_messages = prefix_messages or []\n\n        return cls(\n            llm=llm,\n            memory=memory,\n            prefix_messages=prefix_messages,\n            callback_manager=Settings.callback_manager,\n        )\n\n    @trace_method(\"chat\")\n    def chat(\n        self, message: str, chat_history: Optional[List[ChatMessage]] = None","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/chat_engine/simple.py#L40-L76","documentation":"SimpleChatEngine.from_defaults() raises ValueError when both system_prompt and prefix_messages are passed. As with ContextChatEngine, system_prompt is a convenience that is internally expanded into a one-element prefix_messages list with the model's system role; supplying both is treated as conflicting configuration.","triggerScenarios":"SimpleChatEngine.from_defaults(system_prompt='...', prefix_messages=[...]) — the guard inside the system_prompt branch fires. Common when a generic config dict is splatted into from_defaults.","commonSituations":"Wrapper code that accepts both options for API compatibility and forwards them verbatim; refactoring from prefix_messages to system_prompt without removing the old kwarg; YAML/JSON configs carrying legacy fields.","solutions":["Pass exactly one of system_prompt or prefix_messages","Merge the system message into prefix_messages using role=llm.metadata.system_role if multiple leading messages are needed","Strip empty-string system_prompt values before calling from_defaults (an empty string is still not None and triggers the check)"],"exampleFix":"# before\nengine = SimpleChatEngine.from_defaults(\n    system_prompt='You are terse.',\n    prefix_messages=[ChatMessage(role='system', content='Answer in bullet points')],\n)  # ValueError\n\n# after\nfrom llama_index.core.llms import ChatMessage, MessageRole\nengine = SimpleChatEngine.from_defaults(\n    prefix_messages=[ChatMessage(role=MessageRole.SYSTEM, content='You are terse. Answer in bullet points.')],\n)","handlingStrategy":"validation","validationCode":"assert not (system_prompt and prefix_messages), 'Pass only one of system_prompt or prefix_messages to SimpleChatEngine'","typeGuard":null,"tryCatchPattern":"try:\n    engine = SimpleChatEngine.from_defaults(system_prompt=sp, prefix_messages=pm)\nexcept ValueError as e:\n    if 'Cannot specify both' in str(e):\n        engine = SimpleChatEngine.from_defaults(prefix_messages=pm or None)\n    else:\n        raise","preventionTips":["Sanitize config: treat empty-string system_prompt as None before forwarding","Keep prompt-related settings in one place and validate mutual exclusion there"],"tags":["llama-index","chat-engine","conflicting-arguments","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}