pathwaycom/pathway · critical · ValueError

unexpected value of PATHWAY_SNAPSHOT_ACCESS environment vari

Error message

unexpected value of PATHWAY_SNAPSHOT_ACCESS environment variable - when PATHWAY_REPLAY_STORAGE is set, PATHWAY_SNAPSHOT_ACCESS needs to be set to either 'record' or 'replay'

What it means

Pathway's persistence configuration derives a replay/persistence config only when PATHWAY_SNAPSHOT_ACCESS is exactly 'record' or 'replay'. If PATHWAY_REPLAY_STORAGE is set but the access mode is unset/empty or something else, replay_config raises this ValueError because it cannot decide whether the run should snapshot its state or replay from it.

Source

Thrown at python/pathway/internals/config.py:100

        "PATHWAY_SUPPRESS_OTHER_WORKER_ERRORS"
    )
    metrics_reader_interval_secs: int | None = _env_field(
        "PATHWAY_METRICS_READER_INTERVAL_SECONDS",
        default=None,
        default_if_empty=True,
        _type=int,
    )

    @property
    def replay_config(
        self,
    ) -> persistence.Config | None:
        if self.replay_storage:
            if self.snapshot_access not in (
                api.SnapshotAccess.RECORD,
                api.SnapshotAccess.REPLAY,
            ):
                raise ValueError(
                    "unexpected value of PATHWAY_SNAPSHOT_ACCESS environment variable "
                    + "- when PATHWAY_REPLAY_STORAGE is set, PATHWAY_SNAPSHOT_ACCESS "
                    + "needs to be set to either 'record' or 'replay'"
                )
            data_storage = persistence.Backend.filesystem(self.replay_storage)
            persistence_config = persistence.Config(
                data_storage,
                persistence_mode=self.persistence_mode,
                snapshot_access=self.snapshot_access,
                continue_after_replay=self.continue_after_replay,
            )
            return persistence_config
        else:
            return None


_pathway_config: ContextVar[PathwayConfig] = ContextVar(
    "pathway_config", default=PathwayConfig()

View on GitHub (pinned to fa2f74a464)

Solutions

1. Set PATHWAY_SNAPSHOT_ACCESS=record for the run that should write snapshots, or PATHWAY_SNAPSHOT_ACCESS=replay for a run that should restore from them.
2. Verify both variables together in your deploy scripts: replay storage without an access mode is always invalid.
3. If you did not intend persistence, unset PATHWAY_REPLAY_STORAGE.

Example fix

# before
export PATHWAY_REPLAY_STORAGE=/tmp/snapshots
# PATHWAY_SNAPSHOT_ACCESS not set

# after
export PATHWAY_REPLAY_STORAGE=/tmp/snapshots
export PATHWAY_SNAPSHOT_ACCESS=record

import os
if os.environ.get('PATHWAY_REPLAY_STORAGE'):
    access = os.environ.get('PATHWAY_SNAPSHOT_ACCESS', '').lower()
    assert access in ('record', 'replay'), 'set PATHWAY_SNAPSHOT_ACCESS=record|replay'

When it happens

Trigger: Setting PATHWAY_REPLAY_STORAGE=/tmp/persistence while PATHWAY_SNAPSHOT_ACCESS is empty, unset, or misspelled values like 'Record', 'rec', 'write', or 'run'.

Common situations: Enabling persistence in Docker/K8s by adding only the storage env var; case/typo mistakes; pipelines that previously used the older persistence API upgraded to a version requiring the explicit access mode.

Related errors

• Column {api.DIFF_PSEUDOCOLUMN} can only have 1 and -1 values
• Unexpected value for {name!r} environment variable: {value!r
• Failed to install dependencies
• Column {api.TIME_PSEUDOCOLUMN} cannot contain negative times
• schema does not match given dataframe

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