deepset-ai/haystack · error · ValueError

Invalid pipeline snapshot from {file_path}: {str(e)}

Error message

Invalid pipeline snapshot from {file_path}: {str(e)}

What it means

load_pipeline_snapshot wraps ValueError raised by PipelineSnapshot.from_dict to indicate the JSON file exists but its content is not a valid pipeline snapshot. Haystack throws this when deserializing a snapshot file fails schema/type validation during resume. The original ValueError message is preserved in the new message.

Source

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

        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.

    If a `snapshot_callback` is provided, it will be called with the pipeline snapshot instead of saving to a file.
    This allows users to customize how snapshots are handled (e.g., saving to a database, sending to a remote service).

    When no callback is provided, the default behavior saves to a JSON file:
    - The filename is generated based on the component name, visit count, and timestamp.

View on GitHub (pinned to e318778c9b)

Solutions

1. Inspect the inner message for the exact from_dict failure (missing key / bad type) and fix the snapshot file accordingly
2. Regenerate the snapshot by re-running the pipeline with PipelineDebugger/quit.save or the resume callback so the file matches the current schema
3. Verify the file was written by the same haystack version that is resuming; upgrade/downgrade so versions match
4. Confirm you passed the snapshot JSON file path, not a YAML pipeline file or breakpoint-only file

Example fix

// before
snapshot = load_pipeline_snapshot("hand_edited.json")  # ValueError
// after
import json
data = json.load(open("snapshot.json"))
assert {"pipeline", "runs", "network_status"} <= set(data)  # sanity check
snapshot = load_pipeline_snapshot("snapshot.json")

import json

def can_load_snapshot(path):
    try:
        data = json.load(open(path))
    except Exception:
        return False
    return isinstance(data, dict) and "pipeline" in data

def is_snapshot_dict(obj):
    return isinstance(obj, dict) and isinstance(obj.get("pipeline"), dict)

try:
    snapshot = load_pipeline_snapshot(path)
except (OSError, ValueError) as e:
    logger.error("Cannot resume: %s", e)
    # re-save the snapshot or abort resume

When it happens

Trigger: Calling load_pipeline_snapshot(path) on a file whose parsed dict is missing required PipelineSnapshot keys (pipeline, state, etc.), has wrong types, or was produced by an incompatible haystack version.

Common situations: Hand-edited or truncated snapshot files; snapshots saved by a different haystack version with a changed schema; passing a JSON file that is valid JSON but not a pipeline snapshot (e.g. a tool/sandbox config or breakpoint dump).

Related errors

• Couldn't deserialize component '{name}' of class '{component
• Input '${input_name}' not found in component '${component_na
• Missing mandatory input '${socket_name}' for component '${co
• break_point {break_point} is not a registered component in t
• Invalid pipeline snapshot: components {invalid_ordered_compo

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