pathwaycom/pathway · error · ValueError

Invalid JSON Pointer for field {field_name!r}: {path!r}. JSO

Error message

Invalid JSON Pointer for field {field_name!r}: {path!r}. JSON Pointers (RFC 6901) must be empty or start with '/' (e.g. '/foo/bar').

What it means

Raised when a value in 'json_field_paths' is a non-empty string that does not start with '/'. Pathway locates values inside incoming JSON messages using JSON Pointers as defined in RFC 6901, where a pointer is either the empty string (the whole document) or a slash-prefixed path such as '/foo/bar'. Anything else (e.g. 'foo.bar' or 'foo/0') is rejected before the pipeline starts.

Source

Thrown at python/pathway/io/_utils.py:393

            )
        if json_field_paths is not None:
            schema_columns = set(schema.column_names())
            for field_name, path in json_field_paths.items():
                if field_name == METADATA_COLUMN_NAME:
                    raise ValueError(
                        f"'json_field_paths' cannot be used for "
                        f"{METADATA_COLUMN_NAME!r}: the connector populates "
                        f"this column itself when 'with_metadata=True', so "
                        f"any JSON path would be silently ignored."
                    )
                if field_name not in schema_columns:
                    raise ValueError(
                        f"'json_field_paths' references field {field_name!r} "
                        f"which is not in the schema. Known fields: "
                        f"{sorted(schema_columns)}."
                    )
                if path != "" and not path.startswith("/"):
                    raise ValueError(
                        f"Invalid JSON Pointer for field {field_name!r}: "
                        f"{path!r}. JSON Pointers (RFC 6901) must be empty "
                        f"or start with '/' (e.g. '/foo/bar')."
                    )
        return schema, api.DataFormat(
            **api_schema,
            format_type=data_format_type,
            column_paths=json_field_paths,
            schema_registry_settings=maybe_schema_registry_settings(
                schema_registry_settings
            ),
        )
    else:
        raise ValueError(f"data format `{format}` not supported")


def check_raw_and_plaintext_only_kwargs_for_message_queues(f):
    default_format = inspect.signature(f).parameters["format"].default

View on GitHub (pinned to fa2f74a464)

Solutions

Prefix every non-empty path with '/', e.g. 'user' -> '/user', 'meta.id' -> '/meta/id'.
Use '' (empty string) only when the column should receive the entire JSON document.
Check the message text: it names the exact field whose path is malformed.

Example fix

# before
json_field_paths={'user': 'user', 'meta_id': 'meta.id'}

# after
json_field_paths={'user': '/user', 'meta_id': '/meta/id'}

Defensive patterns

Strategy: validation

Validate before calling

def validate_json_pointers(json_field_paths):
    bad = {f: p for f, p in json_field_paths.items() if p != "" and not p.startswith("/")}
    assert not bad, f"Paths must be RFC 6901 pointers (empty or '/...' ): {bad}"

Type guard

def is_valid_pointer(path: str) -> bool:
    return path == "" or path.startswith("/")

Try / catch

try:
    t = pw.io.kafka.read(..., json_field_paths=paths)
except ValueError as e:
    if "Invalid JSON Pointer" in str(e):
        paths = {f: ('/' + p.lstrip('./')) for f, p in paths.items()}
        t = pw.io.kafka.read(..., json_field_paths=paths)
    else:
        raise

Prevention

Always write pointers slash-first: '/a/b', array index as '/items/0'.
Add a unit check that every path in json_field_paths is '' or startswith('/').

When it happens

Trigger: Passing json_field_paths={'user': 'user'} or {'ts': '.timestamp'} instead of {'user': '/user'}; porting code from a connector that accepted dot-separated paths; forgetting that array indices are written as '/items/0/id'.

Common situations: Developers coming from jq-style or dot-path configs who write 'meta.id' instead of '/meta/id'; the empty-string case is valid (whole payload) which surprises people and leads to guessing at path syntax.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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