microsoft/semantic-kernel · error · ServiceException

An error occurred while applying the template: {template.val

Error message

An error occurred while applying the template: {template.value}

What it means

A catch-all ServiceException thrown when an ONNX chat template function (phi3, phi4, gemma, llama, phi3v, phi4mm) raises an unexpected exception while formatting ChatHistory into the model's expected prompt string. The original error is chained via 'from e' so the __cause__ carries the real exception. This is a secondary error — the root cause is inside the specific template formatter that ran for the chosen ONNXTemplate.

Source

Thrown at python/semantic_kernel/connectors/ai/onnx/utils.py:56

        str: The result of applying the template to the chat history.

    Raises:
        ServiceException: If an error occurs while applying the template.
    """
    template_functions = {
        ONNXTemplate.PHI3: phi3_template,
        ONNXTemplate.PHI4: phi4_template,
        ONNXTemplate.GEMMA: gemma_template,
        ONNXTemplate.LLAMA: llama_template,
        ONNXTemplate.PHI3V: phi3v_template,
        ONNXTemplate.PHI4MM: phi4mm_template,
        ONNXTemplate.NONE: lambda text: text,
    }

    try:
        return template_functions[template](history)
    except Exception as e:
        raise ServiceException(f"An error occurred while applying the template: {template.value}") from e


def phi3_template(history: ChatHistory) -> str:
    """Generates a formatted string from the chat history for use with the phi3 model.

    Args:
        history (ChatHistory): An object containing the chat history with a list of messages.

    Returns:
        str: A formatted string where each message is prefixed with the role and suffixed with an end marker.
    """
    phi3_input = ""
    for message in history.messages:
        phi3_input += f"<|{message.role.value}|>\n{message.content}<|end|>\n"
    phi3_input += "<|assistant|>\n"
    return phi3_input

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the chained exception: catch ServiceException and read exc.__cause__ to see which template function failed and why.
2. Validate ChatHistory before calling the ONNX service — ensure every message has non-None content and a supported AuthorRole for the selected template.
3. Switch to ONNXTemplate.NONE to bypass templating and confirm the error originates in the formatter rather than model inference.
4. File an issue with the __cause__ traceback and the ONNXTemplate value if the formatter itself has a bug.

Example fix

// before
history.add_message(message_with_none_content)
result = service.get_chat_message_contents(history=history)
// after
if message.content is not None:
    history.add_message(message)
result = service.get_chat_message_contents(history=history)

from semantic_kernel.contents import AuthorRole

def validate_history_for_template(history, template_name: str) -> None:
    for msg in history.messages:
        if msg.content is None:
            raise ValueError(f'Message with role {msg.role} has None content — cannot apply {template_name} template')
        if template_name == 'gemma' and msg.role == AuthorRole.SYSTEM:
            raise ValueError('Gemma templates do not support system messages')
        if template_name in ('phi3', 'phi4') and not isinstance(msg.content, str):
            raise ValueError(f'{template_name} template expects string content, got {type(msg.content)}')

def is_valid_chat_history_for_onnx(history) -> bool:
    if not hasattr(history, 'messages') or not isinstance(history.messages, list):
        return False
    return all(m.content is not None for m in history.messages)

from semantic_kernel.exceptions import ServiceException

try:
    result = apply_template(history, template)
except ServiceException as e:
    cause = e.__cause__
    logger.error(f'Template {template.value} failed: {cause}')
    # fallback: use NONE template or repair history

When it happens

Trigger: Calling apply_template() or any ONNX-based chat completion where the selected ONNXTemplate's formatter function throws — e.g. malformed ChatHistory messages, missing content attributes, unsupported message types for that template, or a None message in history.messages.

Common situations: Passing a ChatHistory with empty or None message content to a Gemma/LLaMA formatter; adding image/audio content to a text-only template like phi3; a corrupted or partially-built ChatHistory object from a pipeline; upgrading the SDK and hitting a changed message content contract.

Related errors

• System messages are not supported in Gemma
• Cannot reduce chat history, since the thread is not currentl
• Configuration not found, please setup the notebooks first us
• AZURE_OPENAI_ENDPOINT is not set.
• AZURE_OPENAI_ENDPOINT is not set.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/47a830ab9b6392de. Report an issue: GitHub.