BerriAI/litellm · error · Exception

Failed to load prompt '{encode_prompt_id(prompt_id)}' from G

Error message

Failed to load prompt '{encode_prompt_id(prompt_id)}' from GitLab: {e}

What it means

Wrapper exception from GitLabPromptManager._load_prompt_from_gitlab. Any failure while resolving the repo path, fetching file content, or parsing the .prompt file is re-raised with this message naming the encoded prompt id. The real cause (any of errors 460-462, or a parse error) is chained in the text.

Source

Thrown at litellm/integrations/gitlab/gitlab_prompt_manager.py:142

        path = repo_path.strip("/")
        if self.prompts_path and path.startswith(self.prompts_path.strip("/") + "/"):
            path = path[len(self.prompts_path.strip("/")) + 1 :]
        path = path.removesuffix(".prompt")
        return encode_prompt_id(path)

    # ---------- loading ----------

    def _load_prompt_from_gitlab(self, prompt_id: str, *, ref: str | None = None) -> None:
        """Load a specific .prompt file from GitLab (scoped under prompts_path if set)."""
        try:
            # prompt_id = decode_prompt_id(prompt_id)
            file_path: Final = self._id_to_repo_path(prompt_id)
            prompt_content: Final = self.gitlab_client.get_file_content(file_path, ref=ref)
            if prompt_content:
                template: Final = self._parse_prompt_file(prompt_content, prompt_id)
                self.prompts[prompt_id] = template
        except Exception as e:
            raise Exception(f"Failed to load prompt '{encode_prompt_id(prompt_id)}' from GitLab: {e}")

    def load_all_prompts(self, *, recursive: bool = True) -> list[str]:
        """
        Eagerly load all .prompt files from prompts_path. Returns loaded IDs.
        """
        files: Final = self.list_templates(recursive=recursive)
        loaded: Final[list[str]] = []
        for pid in files:
            if pid not in self.prompts:
                self._load_prompt_from_gitlab(pid)
            loaded.append(pid)
        return loaded

    # ---------- parsing & rendering ----------

    def _parse_prompt_file(self, content: str, prompt_id: str) -> GitLabPromptTemplate:
        if content.startswith("---"):
            parts: Final = content.split("---", 2)

View on GitHub (pinned to 6c2dcb801b)

Solutions

Read the chained exception text to find the underlying cause
Verify the prompt id maps to a real file: check _id_to_repo_path output and list_templates()
Fix token/permissions if the inner error is 401/403
Validate the .prompt file frontmatter if the inner error comes from parsing

Defensive patterns

Strategy: try-catch

Validate before calling

ids = manager.list_templates(recursive=True)
if my_prompt_id not in ids:
    raise LookupError(f"{my_prompt_id} not in repo; available: {ids}")

Try / catch

try:
    manager._load_prompt_from_gitlab(pid)
except Exception as e:
    if "404" in str(e):
        skip(pid)  # tolerate deleted files during bulk load
    else:
        raise

Prevention

Validate prompt ids against list_templates() before loading
During bulk loads, isolate per-file failures instead of aborting all
Parse chained exception text to find root cause

When it happens

Trigger: Calling _load_prompt_from_gitlab, load_all_prompts, get_prompt_template, or compile_prompt_helper for a prompt id whose underlying file fetch or _parse_prompt_file raises: bad credentials, missing access, network failure, or malformed .prompt file content.

Common situations: Bulk-loading all prompts where one file has invalid frontmatter; a renamed/deleted .prompt file still referenced by id; CI environment missing the GitLab token env var so the first fetch 401s; wrong prompts_path prefix.

Related errors

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