pathwaycom/pathway · error · ValueError

Duplicate example id: {id}

Error message

Duplicate example id: {id}

What it means

Raised by EndpointExamples.add_example (the fluent API for documenting HTTP endpoint examples) when the same example id is registered twice. Example ids must be unique within one endpoint because they key the OpenAPI examples map and the request-body dropdown in the generated docs UI.

Source

Thrown at python/pathway/io/http/_server.py:118

    def add_example(self, id, summary, values):
        """
        Adds an example to the collection.

        Args:
            id: Short and unique ID for the example. It is used for naming the example
                within the Open API schema. By using ``default`` as an ID, you can set the example
                default for the readers, while users will be able to select another ones via the
                dropdown menu.
            summary: Human-readable summary of the example, describing what is shown.
                It is shown in the automatically generated dropdown menu.
            values: The key-value dictionary, a mapping from the fields described in
                schema to their values in the example.

        Returns:
            EndpointExamples: The current instance, allowing method chaining.
        """
        if id in self.examples_by_id:
            raise ValueError(f"Duplicate example id: {id}")
        self.examples_by_id[id] = {
            "summary": summary,
            "value": values,
        }
        return self

    def _openapi_description(self):
        return self.examples_by_id


class EndpointDocumentation:
    """
    The settings for the automatic OpenAPI v3 docs generation for an endpoint.

    Args:
        summary: Short endpoint description shown as a hint in the endpoints list.
        description: Comprehensive description for the endpoint.
        tags: Tags for grouping the endpoints.

View on GitHub (pinned to fa2f74a464)

Solutions

  1. Give each example a distinct id: add_example(id="minimal", ...), add_example(id="full", ...).
  2. When overriding a previously added example, replace it deliberately: del endpoint.examples.examples_by_id["default"] before re-adding, or overwrite the dict entry directly.
  3. Deduplicate ids before a loop: assert len(ids) == len(set(ids)).

Example fix

# before
ex.add_example(id="default", summary="basic", values={...})
ex.add_example(id="default", summary="other", values={...})  # ValueError

# after
ex.add_example(id="basic", summary="basic", values={...})
ex.add_example(id="advanced", summary="other", values={...})
Defensive patterns

Strategy: validation

Validate before calling

if example_id in endpoint.examples.examples_by_id:
    raise ValueError(f"example id {example_id!r} already registered")
endpoint.examples.add_example(id=example_id, summary=summary, values=values)

Try / catch

try:
    docs.add_example(id=example_id, summary=summary, values=values)
except ValueError as e:
    if "Duplicate example id" in str(e):
        docs.examples_by_id.pop(example_id, None)  # or overwrite entry directly
        docs.add_example(id=example_id, summary=summary, values=values)
    else:
        raise

Prevention

When it happens

Trigger: Calling http_endpoint(...).request(...).add_example(id="default", ...) twice, or adding examples in a loop where the same id (commonly "default") is reused for different values.

Common situations: Registering a fallback example with id="default" after already adding a default; generating examples from a dict where keys repeat; merging example sets from multiple config sources without id collision checks.

Related errors

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/120be9f36c8491c7. Report an issue: GitHub.