langchain-ai/deepagents · error · ValueError

Provided snapshot_id does not match canonical configuration

Error message

Provided snapshot_id does not match canonical configuration

What it means

HooksSnapshot.from_config recomputes the canonical snapshot id from the config and, if a caller supplies an explicit snapshot_id, verifies it matches. A mismatch means the caller's cached/stored id was computed from different hook configuration, so the library refuses to build a snapshot under a misleading identity with ValueError.

Source

Thrown at libs/code/deepagents_code/hooks/snapshot.py:106

        Args:
            config: Validated Hooks v2 configuration.
            groups: Matcher groups with source provenance. Plain configurations
                use a source with no environment overlay.
            diagnostics: Diagnostics retained from configuration loading.
            snapshot_id: Optional precomputed canonical hash. When omitted, it
                is derived from `config`.

        Returns:
            A snapshot whose handler order, matchers, and id cannot change.

        Raises:
            ValueError: If `snapshot_id` disagrees with the canonical config.
        """
        canonical_id = compute_snapshot_id(config, groups=groups)
        if snapshot_id is not None and snapshot_id != canonical_id:
            msg = "Provided snapshot_id does not match canonical configuration"
            raise ValueError(msg)
        sourced = groups or {
            event: tuple((UNSOURCED, group) for group in event_groups)
            for event, event_groups in config.hooks.items()
        }
        expanded: dict[HookEvent, tuple[HookHandler, ...]] = {}
        compile_diagnostics: list[HookDiagnostic] = list(diagnostics)
        for event, event_groups in sourced.items():
            matcher_field = get_event_spec(event).matcher_field
            handlers: list[HookHandler] = []
            for group_index, (source, group) in enumerate(event_groups):
                if matcher_field is None and group.matcher not in {None, "", "*"}:
                    message = (
                        f"Rejected hook group {event.value}:{group_index}: "
                        f"{event.value} does not support matchers"
                    )
                    logger.warning(message)
                    compile_diagnostics.append(
                        HookDiagnostic(

View on GitHub (pinned to a1af029e6e)

Solutions

Recompute the id: pass snapshot_id=None and use the returned snapshot's snapshot_id, or call compute_snapshot_id(config, groups=groups) and pass that.
If the config intentionally changed, invalidate cached sessions/trust entries and rebuild the snapshot from the new config.
Verify groups passed to from_config match those used when the id was originally computed.
Catch ValueError and fall back to rebuilding the snapshot without an explicit id.

Example fix

// before
snap = HooksSnapshot.from_config(config, snapshot_id=old_cached_id)  # ValueError

// after
snap = HooksSnapshot.from_config(config)  # id computed canonically
use(snapshot_id=snap.snapshot_id)

Defensive patterns

Strategy: validation

Validate before calling

canonical = compute_snapshot_id(config, groups=groups)
if cached_snapshot_id is not None and cached_snapshot_id != canonical:
    cached_snapshot_id = None  # rebuild rather than fail

Try / catch

try:
    snap = HooksSnapshot.from_config(config, snapshot_id=cached_id)
except ValueError as exc:
    if "does not match canonical configuration" in str(exc):
        snap = HooksSnapshot.from_config(config)  # recompute id

Prevention

Never persist and reuse snapshot ids after editing hook config
Compute ids only via compute_snapshot_id
Pass snapshot_id=None unless verifying an externally stored id
Invalidate cached sessions when hook config changes on disk

When it happens

Trigger: Calling HooksSnapshot.from_config(config, snapshot_id="...", ...) where snapshot_id differs from compute_snapshot_id(config, groups=groups) — e.g. a persisted snapshot id reused after the project's hook config changed, or an id computed with different grouping.

Common situations: Editing .deepagents/hooks config while a session's cached snapshot id is still passed in; hand-rolling snapshot ids without compute_snapshot_id; stale trust-store or session metadata referencing an old config hash.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/6d0b79a1c8078aa1. Report an issue: GitHub.