openai/openai-python · error · ValueError

Expected a non-empty value for `fine_tuned_model_checkpoint`

Error message

Expected a non-empty value for `fine_tuned_model_checkpoint` but received {fine_tuned_model_checkpoint!r}

What it means

The fine-tuning checkpoint permissions create method requires a non-empty `fine_tuned_model_checkpoint` path parameter. Despite being named create, it lists permissions via `_get_api_list` on `/fine_tuning/checkpoints/{checkpoint}/permissions`, and the SDK validates the checkpoint id before building the URL, raising ValueError when it is None or empty.

Source

Thrown at src/openai/resources/fine_tuning/checkpoints/permissions.py:83

        """
        **NOTE:** Calling this endpoint requires an [admin API key](../admin-api-keys).

        This enables organization owners to share fine-tuned models with other projects
        in their organization.

        Args:
          project_ids: The project identifiers to grant access to.

          extra_headers: Send extra headers

          extra_query: Add additional query parameters to the request

          extra_body: Add additional JSON properties to the request

          timeout: Override the client-level default timeout for this request, in seconds
        """
        if not fine_tuned_model_checkpoint:
            raise ValueError(
                f"Expected a non-empty value for `fine_tuned_model_checkpoint` but received {fine_tuned_model_checkpoint!r}"
            )
        return self._get_api_list(
            path_template(
                "/fine_tuning/checkpoints/{fine_tuned_model_checkpoint}/permissions",
                fine_tuned_model_checkpoint=fine_tuned_model_checkpoint,
            ),
            page=SyncPage[PermissionCreateResponse],
            body=maybe_transform({"project_ids": project_ids}, permission_create_params.PermissionCreateParams),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                security={"bearer_auth": True},
            ),
            model=PermissionCreateResponse,
            method="post",

View on GitHub (pinned to 9917c6e28e)

Solutions

Use the checkpoint id returned by the fine-tuning job (e.g. from checkpoints list output)
Verify the value is a non-empty string before calling
If unsure of the id, list checkpoints for the job first to resolve it

Example fix

# before
perms = client.fine_tuning.checkpoints.permissions.create(checkpoint_id or "", ...)
# after
if not checkpoint_id:
    raise ValueError("checkpoint_id is required to create permissions")
perms = client.fine_tuning.checkpoints.permissions.create(checkpoint_id, ...)

Defensive patterns

Strategy: validation

Validate before calling

if not fine_tuned_model_checkpoint:
    raise ValueError("checkpoint id is required")
perms = client.fine_tuning.checkpoints.permissions.create(fine_tuned_model_checkpoint, ...)

Type guard

def is_non_empty_id(value: object) -> bool:
    return isinstance(value, str) and bool(value.strip())

Try / catch

try:
    perms = client.fine_tuning.checkpoints.permissions.create(ckpt, ...)
except ValueError as e:
    if "fine_tuned_model_checkpoint" in str(e):
        ckpts = client.fine_tuning.checkpoints.list(fine_tuning_job_id=job_id)
        ckpt = ckpts[0].id
    else:
        raise

Prevention

Capture checkpoint ids when fine-tuning jobs complete
Validate checkpoint ids before permission operations

When it happens

Trigger: Calling `client.fine_tuning.checkpoints.permissions.create(fine_tuned_model_checkpoint="")` or passing None, e.g. when the checkpoint id from a job was not captured.

Common situations: Reading `fine_tuned_model_checkpoint` from a fine-tuning job's events or result objects that omit it; blank values in permission-management scripts; copy-pasted placeholder ids.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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