BerriAI/litellm · error · ValueError

Error compiling prompt '{prompt_id}': {e}

Error message

Error compiling prompt '{prompt_id}': {e}

What it means

ValueError wrapping any failure inside _compile_prompt_helper after the prompt_id guard: BitBucket fetch errors, missing templates, Jinja render errors from malformed templates, YAML frontmatter parse problems, or message-parsing failures all collapse into this single message. The inner exception text is appended, so the root cause is only available as a string. The wrapping to ValueError also erases the distinction between infra errors (should be retried) and content errors (should not).

Source

Thrown at litellm/integrations/bitbucket/bitbucket_prompt_manager.py:480

                "temperature",
                "max_tokens",
                "top_p",
                "frequency_penalty",
                "presence_penalty",
            ]:
                if param in prompt_metadata:
                    optional_params[param] = prompt_metadata[param]

            return PromptManagementClient(
                prompt_id=prompt_id,
                prompt_template=messages,
                prompt_template_model=template_model,
                prompt_template_optional_params=optional_params,
                completed_messages=None,
            )

        except Exception as e:
            raise ValueError(f"Error compiling prompt '{prompt_id}': {e}")

    async def async_compile_prompt_helper(
        self,
        prompt_id: str | None,
        prompt_variables: dict | None,
        dynamic_callback_params: StandardCallbackDynamicParams,
        prompt_spec: PromptSpec | None = None,
        prompt_label: str | None = None,
        prompt_version: int | None = None,
    ) -> PromptManagementClient:
        """
        Async version of compile prompt helper. Since BitBucket operations use sync client,
        this simply delegates to the sync version.
        """
        if prompt_id is None:
            raise ValueError("prompt_id is required for BitBucket prompt manager")

        return self._compile_prompt_helper(

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Read the tail of the message — it contains the underlying exception text; fix that root cause first
2. Test edited .prompt files locally with the same frontmatter parser before committing to BitBucket
3. Separate infrastructure failures (retry) from template errors (fix content) in your error handling around compile_prompt
4. Ensure auth/network are healthy with test_connection() before blaming the template

Example fix

# before
compiled = await client.async_compile_prompt_helper("summary", vars, dynamic_params)

# after (surface the root cause)
try:
    compiled = await client.async_compile_prompt_helper("summary", vars, dynamic_params)
except ValueError as e:
    logger.error("Prompt 'summary' failed to compile: %s", e)
    raise  # fix the underlying issue named in the message

try:
    compiled = await client.async_compile_prompt_helper(prompt_id, variables, dynamic_params)
except ValueError as e:
    msg = str(e)
    if "Authentication failed" in msg or "Access denied" in msg:
        alert_ops(f"BitBucket credential problem: {msg}")
    elif "not found" in msg:
        raise KeyError(f"prompt '{prompt_id}' missing") from e
    else:
        raise  # likely template content error — fix the .prompt file

When it happens

Trigger: Compiling a prompt whose .prompt file has invalid Jinja2 syntax, frontmatter that fails to parse into model/temperature fields, a network/auth failure during _load_prompt_from_bitbucket, or a template id that was never loaded (the 349 error) — any of these is re-wrapped here.

Common situations: Editing a prompt file directly in BitBucket and introducing a typo; environment variable changes breaking auth mid-run; deploying prompt edits without previewing the rendered template.

Related errors

• Failed to load prompt '{prompt_id}' from BitBucket: {e}
• Template '{template_id}' not found
• Prompt template '{prompt_id}' not found
• prompt_id is required for BitBucket prompt manager
• Error calling litellm.acompletion for generate_content: {e}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/a79ba64901d81ffe. Report an issue: GitHub.