BerriAI/litellm · error · ValueError

ref must be a non-empty string

Error message

ref must be a non-empty string

What it means

Raised by GitLabClient.set_ref when the ref argument is falsy (empty string or None after the type hint). set_ref overrides the default tag/branch used for subsequent API calls, and GitLab's repository endpoints require a non-empty ref parameter.

Source

Thrown at litellm/integrations/gitlab/gitlab_client.py:108

        self,
        directory_path: str = "",
        recursive: bool = False,
        *,
        ref: str | None = None,
    ) -> str:
        path_q: Final = f"&path={quote(directory_path, safe='')}" if directory_path else ""
        rec_q: Final = "&recursive=true" if recursive else ""
        ref_q: Final = quote(ref or self.ref, safe="")
        return f"{self.base_url}/projects/{self._project_enc}/repository/tree?ref={ref_q}{path_q}{rec_q}"

    # ------------------------
    # Public API
    # ------------------------

    def set_ref(self, ref: str) -> None:
        """Override the default ref (tag/branch) for subsequent calls."""
        if not ref:
            raise ValueError("ref must be a non-empty string")
        self.ref = ref

    def get_file_content(self, file_path: str, *, ref: str | None = None) -> str | None:
        """
        Fetch the content of a file from the GitLab repository at the given ref
        (tag, branch, or commit SHA). If `ref` is None, uses self.ref.

        Strategy:
          1) Try the RAW endpoint (returns bytes of the file)
          2) Fallback to the JSON endpoint (returns base64-encoded content)

        Returns:
            File content as UTF-8 string, or None if file not found.
        """
        raw_url: Final = self._file_raw_url(file_path, ref=ref)

        try:
            resp: Final = self.http_handler.get(raw_url, headers=self.headers)

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Only call set_ref with a real tag, branch, or commit SHA; skip the call entirely when you want the configured default.
2. Guard callers: if git_ref: client.set_ref(git_ref).
3. Remove empty git_ref keys from config so the override path is never taken with a blank value.

Example fix

# before
client.set_ref(os.getenv("PROMPT_GIT_REF"))  # None when unset -> ValueError

# after
ref = os.getenv("PROMPT_GIT_REF")
if ref:
    client.set_ref(ref)

def apply_ref(client, ref: str | None) -> None:
    if ref is not None and ref.strip():
        client.set_ref(ref.strip())
    # else: keep the configured default ref

def is_usable_ref(ref: object) -> bool:
    return isinstance(ref, str) and bool(ref.strip())

When it happens

Trigger: Calling set_ref('') or set_ref(None) directly; passing a per-prompt git_ref read from config that was defined but left empty (git_ref: in YAML); computing a ref from a variable that is unset at runtime.

Common situations: Config templates that include a git_ref key for all prompts but leave it blank for default-branch prompts; scripts threading an optional ref through and passing the None default instead of skipping the call.

Related errors

• 'models' param not in kwargs
• start_time_utc and end_time_utc must be provided together
• start_time_utc is required for getting a payload from GCS Bu
• gitlab_config is required for gitlab prompt integration
• project and access_token are required

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