pathwaycom/pathway · error · ValueError

'snapshot_name' is not needed for the static mode

Error message

'snapshot_name' is not needed for the static mode

What it means

Raised by _construct_replication_settings when mode="static" is combined with a non-None snapshot_name. Snapshots for replication resume are meaningful only in streaming mode; a static read already takes its own consistent snapshot, so the argument is rejected.

Source

Thrown at python/pathway/io/postgres/__init__.py:264

def _construct_replication_settings(
    *,
    mode: Literal["streaming", "static"],
    postgres_settings: dict,
    publication_name: str | None,
    replication_slot_name: str | None,
    snapshot_name: str | None,
):
    # static mode doesn't require replication slots
    if mode == "static":
        if publication_name is not None:
            raise ValueError("'publication_name' is not needed for the static mode")
        if replication_slot_name is not None:
            raise ValueError(
                "'replication_slot_name' is not needed for the static mode"
            )
        if snapshot_name is not None:
            raise ValueError("'snapshot_name' is not needed for the static mode")
        return None
    if publication_name is None:
        raise ValueError("'publication_name' is required for the streaming mode")

    # streaming mode: user provides publication, we create the slot
    replication_slot_defined = replication_slot_name is None
    snapshot_name_defined = snapshot_name is None
    if replication_slot_defined != snapshot_name_defined:
        raise ValueError(
            "Either none or both of 'replication_slot_name', 'snapshot_name' must be specified"
        )

    return api.PsqlReplicationSettings(
        connection_string=(
            _replication_connection_string_from_settings(postgres_settings)
        ),
        publication_name=publication_name,
        snapshot_name=snapshot_name,

View on GitHub (pinned to fa2f74a464)

Solutions

1. Remove snapshot_name from the static-mode call.
2. Remove publication_name/replication_slot_name too if present (sibling checks).

Example fix

# before
pw.io.postgres.read(parts, "tbl", mode="static", snapshot_name="snap1")
# after
pw.io.postgres.read(parts, "tbl", mode="static")

if mode == "static":
    assert snapshot_name is None, "snapshot_name is streaming-only"

When it happens

Trigger: pw.io.postgres.read(..., mode="static", snapshot_name="mysnap").

Common situations: Porting an existing streaming read with an exported snapshot to a static backfill job; IDE autocompleting all replication kwargs.

Related errors

• 'publication_name' is not needed for the static mode
• 'replication_slot_name' is not needed for the static mode
• 'publication_name' is required for the streaming mode
• Either none or both of 'replication_slot_name', 'snapshot_na
• pw.io.mssql.read requires at least one primary key column in

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