openai/openai-python · critical · SubjectTokenProviderError

Failed to read the token file at {token_file_path}: {e}

Error message

Failed to read the token file at {token_file_path}: {e}

What it means

The outer handler for the workload token file reader: any exception while opening/reading the token file (FileNotFoundError, PermissionError, IsADirectoryError, UnicodeDecodeError, or the empty-file SubjectTokenProviderError itself) is wrapped in SubjectTokenProviderError with the underlying cause chained. The message includes the original exception text, which tells you whether it is a path, permission, or emptiness problem.

Source

Thrown at src/openai/auth/_workload.py:98

) -> SubjectTokenProvider:
    """
    Get a subject token provider for Kubernetes clusters with Workload Identity configured.

    Cloud providers typically mount the subject token as a file in the container.

    Args:
        token_file_path: path to the mounted service account token file. Defaults to `/var/run/secrets/kubernetes.io/serviceaccount/token`.
    """

    def get_token() -> str:
        try:
            with open(token_file_path, "r") as f:
                token = f.read().strip()
                if not token:
                    raise SubjectTokenProviderError(f"The token file at {token_file_path} is empty.")
                return token
        except Exception as e:
            raise SubjectTokenProviderError(f"Failed to read the token file at {token_file_path}: {e}") from e

    return {"token_type": "jwt", "get_token": get_token}


def azure_managed_identity_token_provider(
    resource: str = "https://management.azure.com/",
    *,
    object_id: str | None = None,
    client_id: str | None = None,
    msi_res_id: str | None = None,
    api_version: str = "2018-02-01",
    timeout: float = 10.0,
    http_client: httpx2.Client | None = None,
) -> SubjectTokenProvider:
    """
    Get a subject token provider for Azure Managed Identities.

    See: https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Read the chained exception (__cause__) to identify FileNotFound vs Permission vs empty
2. Verify the exact path exists and is readable: ls -l and cat the file inside the pod
3. Fix the volume mount / path so it points at the projected token file
4. Fall back to OPENAI_API_KEY or another credential when not running in the cluster

Example fix

# before
provider = token_provider("/var/run/secrets/tokens/oidc-token")  # wrong path

# after
provider = token_provider("/var/run/secrets/kubernetes.io/serviceaccount/token")  # actual mount

import os
assert os.path.isfile(TOKEN_PATH) and os.access(TOKEN_PATH, os.R_OK), TOKEN_PATH

def token_file_readable(path: str) -> bool:
    import os
    return os.path.isfile(path) and os.access(path, os.R_OK) and bool(open(path).read(1024).strip())

try:
    token = provider["get_token"]()
except SubjectTokenProviderError as e:
    diagnose(e.__cause__)  # FileNotFoundError vs PermissionError vs empty

When it happens

Trigger: Token file path does not exist (FileNotFoundError), wrong permissions (PermissionError), path is a directory, binary/undecodable content, or empty file — any of these during get_token() for workload identity auth.

Common situations: Wrong token file path in provider config (common when the pod spec differs from local assumptions); read-only root filesystem permission quirks; env var pointing to nonexistent mount; local development without the cluster-mounted secret.

Related errors

• The token file at {token_file_path} is empty.
• The `api_key` and `workload_identity` arguments are mutually
• Invalid `workload_identity` configuration: expected an X.509
• X.509 workload identity cannot be changed after client const
• Missing credentials. Please pass an `api_key`, `workload_ide

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/5160354fd9a54261. Report an issue: GitHub.