BerriAI/litellm · error · HTTPException

Invalid purpose: {purpose}. Must be one of: {valid_purposes}

Error message

Invalid purpose: {purpose}. Must be one of: {valid_purposes}

What it means

HTTPException(400) raised while validating the 'purpose' form field on file upload: the supplied purpose is not one of the allowed values (the valid list is included in the message). The OpenAI files API only accepts specific purpose strings; the client must correct the value.

Source

Thrown at litellm/proxy/openai_files_endpoints/files_endpoints.py:367

        file_params: Final = await extract_file_creation_params(
            request=request,
            request_body=request_body,
            target_model_names_form=target_model_names,
            target_storage_form=target_storage,
        )

        target_storage = file_params.target_storage
        target_model_names_list: Final = file_params.target_model_names
        model_param: Final = file_params.model

        validate_managed_files_requirement(target_model_names=target_model_names_list, model=model_param)

        # Prepare the data for forwarding

        # Replace with:
        valid_purposes: Final = get_args(OpenAIFilesPurpose)
        if purpose not in valid_purposes:
            raise HTTPException(
                status_code=400,
                detail={
                    "error": f"Invalid purpose: {purpose}. Must be one of: {valid_purposes}",
                },
            )
        # Cast purpose to OpenAIFilesPurpose type
        purpose = cast(OpenAIFilesPurpose, purpose)

        data = {}

        # Parse expires_after if provided
        expires_after: FileExpiresAfter | None = None
        form_data_raw: Final = await request.form()
        form_data_dict: Final[dict[str, Any]] = dict(form_data_raw)
        extracted_litellm_metadata: Final[dict[str, Any] | None] = extract_nested_form_metadata(
            form_data=form_data_dict, prefix="litellm_metadata["
        )
        expires_after_anchor: Final = form_data_raw.get("expires_after[anchor]")

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Use one of the valid purposes listed in the error for the 'purpose' field.

When it happens

Trigger: Thrown at litellm/proxy/openai_files_endpoints/files_endpoints.py:367 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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