pathwaycom/pathway · error · ValueError

Unexpected value for {name!r} environment variable: {value!r

Error message

Unexpected value for {name!r} environment variable: {value!r}

What it means

Pathway's runtime configuration parses boolean fields from environment variables, accepting only 1/true/yes (case-insensitive) as true and 0/false/no as false. Any other value for a boolean PATHWAY_* env var (e.g. PATHWAY_MONITORING_XML) makes the config dataclass factory raise a ValueError at config-construction time.

Source

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

        value = os.environ.get(name, default)
        if default_if_empty and value == "":
            value = default
        if value is not None:
            return _type(value)
        return value

    return field(default_factory=factory)


def _env_bool_field(name: str, *, default: str = "false"):
    def factory():
        value = os.environ.get(name, default).lower()
        if value in ("1", "true", "yes"):
            return True
        elif value in ("0", "false", "no"):
            return False
        else:
            raise ValueError(
                f"Unexpected value for {name!r} environment variable: {value!r}"
            )

    return field(default_factory=factory)


def _snapshot_access() -> api.SnapshotAccess | None:
    match os.environ.get("PATHWAY_SNAPSHOT_ACCESS", "").lower():
        case "record":
            return api.SnapshotAccess.RECORD
        case "replay":
            return api.SnapshotAccess.REPLAY
        case _:
            return None


def _persistence_mode() -> api.PersistenceMode:
    match os.environ.get(

View on GitHub (pinned to fa2f74a464)

Solutions

1. Set the variable to one of the accepted literals: 1/true/yes or 0/false/no (lowercased before comparison, so case does not matter).
2. Unset the variable entirely if you want the default, especially avoid empty-string values: use `unset VAR` or remove the line from the env file (docker-compose: comment it out rather than leaving VAR=).
3. Audit all PATHWAY_* booleans in your deployment env (env | grep ^PATHWAY_) and normalize them.

Example fix

# before (docker-compose.yml)
environment:
  PATHWAY_MONITORING_XML: "on"

# after
environment:
  PATHWAY_MONITORING_XML: "true"

import os
_TRUE, _FALSE = {'1','true','yes'}, {'0','false','no'}
for name in ['PATHWAY_MONITORING_XML', 'PATHWAY_CONTINUOUS_LOGGING']:
    v = os.environ.get(name)
    if v is not None:
        assert v.lower() in _TRUE | _FALSE, f'{name}={v!r} not a recognized boolean'

When it happens

Trigger: Setting PATHWAY_MONITORING_XML=on, PATHWAY_PERSISTENCE=enable, or PATHWAY_CONTINUOUS_LOGGING=TRUE-ish variants like 'TrUe' are fine, but values like 'on', 'enabled', 'yes please', or an empty string for vars whose default kicks in only when unset all fail.

Common situations: Docker/Kubernetes env files using ON/OFF conventions; typos like 'fasle'; CI injecting empty strings (NAME="") which override the default and then fail parsing.

Related errors

• unexpected value of PATHWAY_SNAPSHOT_ACCESS environment vari
• Failed to install dependencies
• Column {api.TIME_PSEUDOCOLUMN} cannot contain negative times
• Column {api.DIFF_PSEUDOCOLUMN} can only have 1 and -1 values
• schema does not match given dataframe

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