openai/openai-python · error · KeyError

a value for placeholder {{{name}}} was not provided

Error message

a value for placeholder {{{name}}} was not provided

What it means

path_template builds URL paths from templates containing {placeholder} segments; _interpolate splits the template and requires a value in the provided kwargs mapping for every placeholder. This KeyError means a path parameter required by the method's URL template was not supplied — the SDK guarantees all placeholders are declared required, so in practice it fires when calling resource methods through reflection or with programmatically-built kwargs that omit a path parameter.

Source

Thrown at src/openai/_utils/_path.py:66

    template: str,
    values: Mapping[str, Any],
    quoter: Callable[[str], str],
) -> str:
    """Replace {name} placeholders in `template`, quoting each value with `quoter`.

    Placeholder names are looked up in `values`.

    Raises:
        KeyError: If a placeholder is not found in `values`.
    """
    # re.split with a capturing group returns alternating
    # [text, name, text, name, ..., text] elements.
    parts = _PLACEHOLDER_RE.split(template)

    for i in range(1, len(parts), 2):
        name = parts[i]
        if name not in values:
            raise KeyError(f"a value for placeholder {{{name}}} was not provided")
        val = values[name]
        if val is None:
            parts[i] = "null"
        elif isinstance(val, bool):
            parts[i] = "true" if val else "false"
        else:
            parts[i] = quoter(str(values[name]))

    return "".join(parts)


def path_template(template: str, /, **kwargs: Any) -> str:
    """Interpolate {name} placeholders in `template` from keyword arguments.

    Args:
        template: The template string containing {name} placeholders.
        **kwargs: Keyword arguments to interpolate into the template.

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Check the method signature and pass every path parameter as an explicit keyword argument
2. Fix typos: the kwargs key must exactly match the placeholder name in the URL template
3. If building calls dynamically, inspect the template's placeholders and assert your kwargs cover them before invoking
4. Catch KeyError to fail fast with a clearer message in reflection-based wrappers

Example fix

# before
client.resources.delete()  # missing id

# after
client.resources.delete("res_123")

import inspect, re
params = set(re.findall(r"\{(\w+)\}", template))
missing = params - set(kwargs)
assert not missing, f"missing: {missing}"

def has_all_path_params(template: str, kwargs: dict) -> bool:
    import re
    return set(re.findall(r"\{(\w+)\}", template)) <= set(kwargs)

try:
    method(**kwargs)
except KeyError as e:
    raise ValueError(f"call missing path param: {e}") from e

When it happens

Trigger: Calling an endpoint method with a URL template like /resources/{id} without the corresponding keyword argument, or passing the value inside a body/extra kwargs object instead of as its own keyword; dynamic dispatch that forwards an incomplete kwargs dict.

Common situations: Generic wrappers that map HTTP verbs to SDK methods and drop path params; typos in the parameter name (value passed as obj_id instead of id); copy-pasted calls missing the id argument.

Related errors

• {func.__name__}() takes {len(positional)} argument(s) but {l
• Missing required arguments: {human_join([quote(arg) for arg

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