BerriAI/litellm · error · Exception

Unmapped prompt format. Your prompt is neither a list of str

Error message

Unmapped prompt format. Your prompt is neither a list of strings nor a string. prompt={prompt}. File an issue - https://github.com/BerriAI/litellm/issues

What it means

litellm.text_completion() accepts prompt as a plain string, a list of strings, or — for token-ID inputs — a list of ints / list of list of ints, and the token-ID form is only allowed for openai, azure, azure_text, text-completion-codestral and text-completion-openai providers. Any other shape raises this Exception.

Source

Thrown at litellm/main.py:7327

            messages.append(message)
    elif isinstance(prompt, str):
        messages = [{"role": "user", "content": prompt}]
    elif (
        (
            custom_llm_provider == "openai"
            or custom_llm_provider == "azure"
            or custom_llm_provider == "azure_text"
            or custom_llm_provider == "text-completion-codestral"
            or custom_llm_provider == "text-completion-openai"
        )
        and isinstance(prompt, list)
        and len(prompt) > 0
        and (isinstance(prompt[0], list) or isinstance(prompt[0], int))
    ):
        # Support for token IDs as prompt (list of integers or list of lists of integers)
        messages = [{"role": "user", "content": prompt}]
    else:
        raise Exception(
            f"Unmapped prompt format. Your prompt is neither a list of strings nor a string. prompt={prompt}. File an issue - https://github.com/BerriAI/litellm/issues"
        )

    kwargs.pop("prompt", None)

    if (
        _model is not None and (custom_llm_provider == "openai")
    ):  # for openai compatible endpoints - e.g. vllm, call the native /v1/completions endpoint for text completion calls
        if _model not in litellm.open_ai_chat_completion_models:
            model = "text-completion-openai/" + _model
            optional_params.pop("custom_llm_provider", None)

    if model is None:
        raise ValueError("model is not set. Set either via 'model' or 'engine' param.")
    kwargs["text_completion"] = True
    response = completion(
        model=model,
        messages=messages,

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Pass a string: litellm.text_completion(model='gpt-3.5-turbo-instruct', prompt='Once upon a time')
2. For message dicts, use litellm.completion(model=..., messages=[...]) instead
3. For token IDs, use an allowed provider (model='text-completion-openai/...' or an azure variant)
4. Normalize prompt to str or list[str] before calling

Example fix

# before
resp = litellm.text_completion(model="gpt-3.5-turbo-instruct", prompt=[{"role": "user", "content": "hi"}])

# after
resp = litellm.completion(model="gpt-4o-mini", messages=[{"role": "user", "content": "hi"}])

TOKEN_ID_PROVIDERS = {"openai", "azure", "azure_text", "text-completion-codestral", "text-completion-openai"}

def is_valid_text_prompt(prompt, provider: str) -> bool:
    if isinstance(prompt, str):
        return True
    if isinstance(prompt, list) and prompt and all(isinstance(p, str) for p in prompt):
        return True
    if (
        provider in TOKEN_ID_PROVIDERS
        and isinstance(prompt, list)
        and prompt
        and (isinstance(prompt[0], int) or isinstance(prompt[0], list))
    ):
        return True
    return False

def is_valid_text_prompt(prompt: object) -> bool:
    if isinstance(prompt, str):
        return True
    if isinstance(prompt, list):
        if not prompt:
            return False
        return isinstance(prompt[0], (str, int)) or isinstance(prompt[0], list)
    return False

try:
    resp = litellm.text_completion(model=model, prompt=prompt)
except Exception as e:
    if "Unmapped prompt format" in str(e):
        raise TypeError(f"bad prompt shape: {type(prompt)}") from e
    raise

When it happens

Trigger: text_completion(model=..., prompt=[{'role': 'user', 'content': ...}]) (chat messages fed to prompt); prompt being an int, dict or None; or token-ID lists used with a provider outside the supported set.

Common situations: Porting completion() code to text_completion() and passing messages unchanged; sending pre-tokenized inputs to a non-OpenAI legacy endpoint; a upstream library handing back dicts where strings were expected.

Related errors

• prompt_id is required when prompt_file is provided
• Prompt directory does not exist: {self.prompt_directory}
• Invalid YAML frontmatter: {e}
• Prompt '{prompt_id}'{version_str} not found. Available promp
• Error rendering template '{prompt_id}': {e}

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/16215c20c3a88982. Report an issue: GitHub.