deepset-ai/haystack · error · OSError

Error reading {file_path}: {str(e)}

Error message

Error reading {file_path}: {str(e)}

What it means

load_pipeline_snapshot() wraps OSError when reading the snapshot file fails and re-raises OSError with the path and the OS error text. This distinguishes permission/IO problems from the not-found and invalid-JSON cases handled in neighboring branches.

Source

Thrown at haystack/core/pipeline/breakpoint.py:120

    """
    Load a saved pipeline snapshot.

    :param file_path: Path to the pipeline_snapshot file.
    :returns:
        Dict containing the loaded pipeline_snapshot.
    """

    file_path = Path(file_path)

    try:
        with open(file_path, encoding="utf-8") as f:
            pipeline_snapshot_dict = json.load(f)
    except FileNotFoundError as e:
        raise FileNotFoundError(f"File not found: {file_path}") from e
    except json.JSONDecodeError as e:
        raise json.JSONDecodeError(f"Invalid JSON file {file_path}: {str(e)}", e.doc, e.pos) from e
    except OSError as e:
        raise OSError(f"Error reading {file_path}: {str(e)}") from e

    try:
        pipeline_snapshot = PipelineSnapshot.from_dict(pipeline_snapshot_dict)
    except ValueError as e:
        raise ValueError(f"Invalid pipeline snapshot from {file_path}: {str(e)}") from e

    logger.info("Successfully loaded the pipeline snapshot from: {file_path}", file_path=file_path)
    return pipeline_snapshot


def _save_pipeline_snapshot(
    pipeline_snapshot: PipelineSnapshot,
    raise_on_failure: bool = True,
    snapshot_callback: SnapshotCallback | None = None,
) -> str | None:
    """
    Save the pipeline snapshot dictionary to a JSON file, or invoke a custom callback.

View on GitHub (pinned to e318778c9b)

Solutions

1. Fix permissions on the file (chmod/chown) or run as a user with read access.
2. Verify the path points to a regular file, not a directory or broken mount, and that the storage is reachable.
3. Copy the snapshot to a local readable location and load it from there.

Example fix

// before
snapshot = load_pipeline_snapshot("/mnt/net/snapshot.json")  # mount down
// after
import shutil, os
local = "/tmp/snapshot.json"
shutil.copy("/mnt/net/snapshot.json", local)  # after restoring mount
snapshot = load_pipeline_snapshot(local)

p = Path(file_path)
if not p.is_file():
    raise OSError(f"Not a readable file: {p}")
if not os.access(p, os.R_OK):
    raise PermissionError(f"No read permission: {p}")

def can_read(path) -> bool:
    import os
    from pathlib import Path
    p = Path(path)
    return p.is_file() and os.access(p, os.R_OK)

try:
    snapshot = load_pipeline_snapshot(file_path)
except OSError as e:
    logger.error("Cannot read snapshot %s: %s", file_path, e)

When it happens

Trigger: Calling load_pipeline_snapshot() on a file without read permission, on a directory, on an unreadable network mount, or a device/dis I/O failure while opening/reading the file.

Common situations: Snapshot saved by another user with restrictive permissions; file locked or on a disconnected network drive; passing a directory path instead of a JSON file.

Related errors

• File not found: {file_path}
• Invalid pipeline snapshot: components {invalid_ordered_compo
• Invalid pipeline snapshot: components {invalid_input_data} i
• Invalid pipeline snapshot: components {invalid_component_vis
• The following tool names are not valid: {invalid_tool_names}

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/f2ce02205f813c85. Report an issue: GitHub.