{"record":{"id":"51ec1619af9ff06d","repo":"run-llama/llama_index","slug":"cannot-specify-both-system-prompt-and-prefix-messa","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/context.py","lineNumber":119,"sourceCode":"        system_prompt: Optional[str] = None,\n        prefix_messages: Optional[List[ChatMessage]] = None,\n        node_postprocessors: Optional[List[BaseNodePostprocessor]] = None,\n        context_template: Optional[Union[str, PromptTemplate]] = None,\n        context_refine_template: Optional[Union[str, PromptTemplate]] = None,\n        llm: Optional[LLM] = None,\n        **kwargs: Any,\n    ) -> \"ContextChatEngine\":\n        \"\"\"Initialize a ContextChatEngine from default parameters.\"\"\"\n        llm = llm or Settings.llm\n\n        chat_history = chat_history or []\n        memory = memory or Memory.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        node_postprocessors = node_postprocessors or []\n\n        return cls(\n            retriever,\n            llm=llm,\n            memory=memory,\n            prefix_messages=prefix_messages,\n            node_postprocessors=node_postprocessors,\n            callback_manager=Settings.callback_manager,\n            context_template=context_template,\n            context_refine_template=context_refine_template,","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/chat_engine/context.py#L101-L137","documentation":"ContextChatEngine.from_defaults() raises ValueError when both system_prompt and prefix_messages are supplied. The two parameters are alternative ways to seed the leading messages: system_prompt is shorthand that gets converted into a single system-role prefix message, so providing both makes the intent ambiguous and the engine refuses to guess which to keep.","triggerScenarios":"ContextChatEngine.from_defaults(retriever=r, system_prompt='You are...', prefix_messages=[ChatMessage(...)]) — the inner `if prefix_messages is not None` check fires when system_prompt was already provided.","commonSituations":"Config systems that set both a 'system prompt' field and an 'advanced' prefix_messages field; incrementally adding prefix_messages for few-shot examples without removing an earlier system_prompt; merging code from two examples.","solutions":["Keep only one: pass system_prompt for a plain system message, or prefix_messages when you need multiple/role-controlled leading messages","If you need both a system message and extra prefix messages, fold the system message into prefix_messages with role=llm.metadata.system_role","Audit shared builder functions that blindly forward both kwargs"],"exampleFix":"# before\nengine = ContextChatEngine.from_defaults(\n    retriever=r,\n    system_prompt='You are a helpful assistant.',\n    prefix_messages=[ChatMessage(role='system', content='Be terse')],\n)  # ValueError\n\n# after\nfrom llama_index.core.llms import ChatMessage, MessageRole\nengine = ContextChatEngine.from_defaults(\n    retriever=r,\n    prefix_messages=[\n        ChatMessage(role=MessageRole.SYSTEM, content='You are a helpful assistant. Be terse.'),\n    ],\n)","handlingStrategy":"validation","validationCode":"if system_prompt is not None:\n    assert prefix_messages is None, 'Pass only one of system_prompt or prefix_messages to ContextChatEngine'","typeGuard":null,"tryCatchPattern":"try:\n    engine = ContextChatEngine.from_defaults(retriever=r, system_prompt=sp, prefix_messages=pm)\nexcept ValueError as e:\n    if 'Cannot specify both' in str(e):\n        engine = ContextChatEngine.from_defaults(retriever=r, prefix_messages=pm or None)\n    else:\n        raise","preventionTips":["Model chat-engine options as mutually exclusive fields in your config schema","Drop unset/None kwargs before calling from_defaults to avoid accidental conflicts"],"tags":["llama-index","chat-engine","conflicting-arguments","validation"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}