openai/openai-python · error · ValueError

Expected a non-empty value for `role_id` but received {role_

Error message

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

What it means

Raised client-side by the openai-python SDK before any HTTP request. Retrieving a group role via client.admin.organization.projects.groups.roles.retrieve(...) requires a non-empty role_id because it is the final path segment in /projects/{project_id}/groups/{group_id}/roles/{role_id}. An empty role_id would resolve to the collection URL, so the SDK validates it and raises ValueError with the received value.

Source

Thrown at src/openai/resources/admin/organization/projects/groups/roles.py:120

    ) -> RoleRetrieveResponse:
        """
        Retrieves a project role assigned to a group.

        Args:
          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 project_id:
            raise ValueError(f"Expected a non-empty value for `project_id` but received {project_id!r}")
        if not group_id:
            raise ValueError(f"Expected a non-empty value for `group_id` but received {group_id!r}")
        if not role_id:
            raise ValueError(f"Expected a non-empty value for `role_id` but received {role_id!r}")
        return self._get(
            path_template(
                "/projects/{project_id}/groups/{group_id}/roles/{role_id}",
                project_id=project_id,
                group_id=group_id,
                role_id=role_id,
            ),
            options=make_request_options(
                extra_headers=extra_headers,
                extra_query=extra_query,
                extra_body=extra_body,
                timeout=timeout,
                security={"admin_api_key_auth": True},
            ),
            cast_to=RoleRetrieveResponse,
        )

    def list(

View on GitHub (pinned to 9917c6e28e)

Solutions

  1. Confirm you are passing the role's id string (e.g. role.id), not the object or an empty variable.
  2. List existing roles to find valid ids before retrieving.
  3. Make the role id a required config value validated at startup.

Example fix

# before
role = client.admin.organization.projects.groups.roles.retrieve(project_id=pid, group_id=gid, role_id=settings.get("role"))

# after
role_id = settings["role_id"]
role = client.admin.organization.projects.groups.roles.retrieve(project_id=pid, group_id=gid, role_id=role_id)
Defensive patterns

Strategy: validation

Validate before calling

if not role_id:
    raise ValueError(f"role_id required; got {role_id!r}")
role = client.admin.organization.projects.groups.roles.retrieve(project_id=project_id, group_id=group_id, role_id=role_id)

Type guard

def valid_role_id(rid: object) -> bool:
    return isinstance(rid, str) and rid.strip() != ""

Try / catch

try:
    role = client.admin.organization.projects.groups.roles.retrieve(project_id=pid, group_id=gid, role_id=rid)
except ValueError as e:
    if "role_id" in str(e):
        rid = find_role_id(client, pid, gid)
    else:
        raise

Prevention

When it happens

Trigger: Calling roles.retrieve(project_id=..., group_id=..., role_id='') where role_id is None or empty — commonly a custom role id loaded from config that was never defined, or a builtin role name misspelled to an empty variable.

Common situations: Using custom role ids from an org settings file that lacks the entry; assuming role names like 'member' work where a role resource id is required; passing the whole role object instead of its id field.

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/6c35da99b0673443. Report an issue: GitHub.