langchain-ai/deepagents · error · ValueError

a {self.status.health.value} snapshot must carry no data; an

Error message

a {self.status.health.value} snapshot must carry no data; an empty table is what every reader reads as 'nothing declared'

What it means

TomlSnapshot enforces the invariant that only a healthy (OK) snapshot may carry parsed table data. When health is degraded (e.g. missing, unreadable, invalid) the snapshot must have an empty data dict, because readers treat an empty table as 'nothing declared'; attaching data to a non-OK snapshot would make its status ambiguous. Raised from `__post_init__`.

Source

Thrown at libs/code/deepagents_code/configuration/types.py:188

        copies its own mappings. It is a raw TOML table, and the coercers test
        nested values with `isinstance(value, dict)` to tell a table from a
        scalar -- so any `Mapping` that is not a `dict` fails that test and
        every option under it falls back to its next source, silently. The
        narrower annotation makes a `mappingproxy` (or any other `Mapping`) a
        type error at the call site rather than a fall-through at runtime.

        The immutability this type promises is therefore a convention, kept by
        the providers that build the snapshot and by callers handed one.

        Raises:
            ValueError: If an unhealthy snapshot carries a non-empty table.
        """
        if self.status.health is not ProviderHealth.OK and self.data:
            msg = (
                f"a {self.status.health.value} snapshot must carry no data; an "
                "empty table is what every reader reads as 'nothing declared'"
            )
            raise ValueError(msg)

    @classmethod
    def from_table(cls, name: str, data: dict[str, Any]) -> TomlSnapshot:
        """Build a readable snapshot around an already-parsed table.

        For a caller that holds the parsed data and no health metadata of its
        own. A caller that has real health passes both halves directly.

        Args:
            name: Human-readable source label.
            data: Parsed TOML table.

        Returns:
            An `OK` snapshot carrying `data`.
        """
        return cls(data, ProviderStatus(name, None, ProviderHealth.OK))

    @classmethod

View on GitHub (pinned to a1af029e6e)

Solutions

1. Pass data={} (or omit data) when the health is not OK
2. Only attach data via TomlSnapshot.from_table on snapshots whose health is OK
3. Fix the underlying health problem (file missing/unreadable/invalid) so an OK snapshot can legitimately carry the data
4. In caching code, drop the parsed table whenever the health status downgrades

Example fix

// before
TomlSnapshot(name="tools", status=failed_status, data=parsed_table)
// after
TomlSnapshot(name="tools", status=failed_status, data={})

from deepagents_code.configuration.types import TomlSnapshot, ProviderHealth

def safe_snapshot(name: str, status, data: dict) -> TomlSnapshot:
    healthy = status.health is ProviderHealth.OK
    return TomlSnapshot(name=name, status=status, data=data if healthy else {})

def is_consistent_snapshot(snap: TomlSnapshot) -> bool:
    from deepagents_code.configuration.types import ProviderHealth
    return snap.status.health is ProviderHealth.OK or not snap.data

try:
    snap = TomlSnapshot(name=name, status=status, data=data)
except ValueError as exc:
    if "must carry no data" in str(exc):
        snap = TomlSnapshot(name=name, status=status, data={})
    else:
        raise

When it happens

Trigger: Constructing TomlSnapshot (or from_table with mismatched args) where status.health is not ProviderHealth.OK (e.g. 'missing', 'unreadable', 'invalid') while data is a non-empty dict — e.g. TomlSnapshot(status=snapshot_status_with_health_error, data={"key": 1}).

Common situations: Manually building snapshots in tests or tooling with stale data kept alongside an error status; caching parsed TOML and then marking the snapshot failed without clearing data; a migration that changed health values but kept old data.

Related errors

• a failed write must carry an error detail
• a failed write cannot have changed the file
• a successful write cannot carry an error detail
• -32002
• -32602

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