{"record":{"id":"72ddfa50ad56a1d7","repo":"langchain-ai/deepagents","slug":"a-self-status-health-value-snapshot-must-carry-n","errorCode":null,"errorMessage":"a {self.status.health.value} snapshot must carry no data; an empty table is what every reader reads as 'nothing declared'","messagePattern":"a (.+?) snapshot must carry no data; an empty table is what every reader reads as 'nothing declared'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/configuration/types.py","lineNumber":188,"sourceCode":"        copies its own mappings. It is a raw TOML table, and the coercers test\n        nested values with `isinstance(value, dict)` to tell a table from a\n        scalar -- so any `Mapping` that is not a `dict` fails that test and\n        every option under it falls back to its next source, silently. The\n        narrower annotation makes a `mappingproxy` (or any other `Mapping`) a\n        type error at the call site rather than a fall-through at runtime.\n\n        The immutability this type promises is therefore a convention, kept by\n        the providers that build the snapshot and by callers handed one.\n\n        Raises:\n            ValueError: If an unhealthy snapshot carries a non-empty table.\n        \"\"\"\n        if self.status.health is not ProviderHealth.OK and self.data:\n            msg = (\n                f\"a {self.status.health.value} snapshot must carry no data; an \"\n                \"empty table is what every reader reads as 'nothing declared'\"\n            )\n            raise ValueError(msg)\n\n    @classmethod\n    def from_table(cls, name: str, data: dict[str, Any]) -> TomlSnapshot:\n        \"\"\"Build a readable snapshot around an already-parsed table.\n\n        For a caller that holds the parsed data and no health metadata of its\n        own. A caller that has real health passes both halves directly.\n\n        Args:\n            name: Human-readable source label.\n            data: Parsed TOML table.\n\n        Returns:\n            An `OK` snapshot carrying `data`.\n        \"\"\"\n        return cls(data, ProviderStatus(name, None, ProviderHealth.OK))\n\n    @classmethod","sourceCodeStart":170,"sourceCodeEnd":206,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/configuration/types.py#L170-L206","documentation":"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__`.","triggerScenarios":"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}).","commonSituations":"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.","solutions":["Pass data={} (or omit data) when the health is not OK","Only attach data via TomlSnapshot.from_table on snapshots whose health is OK","Fix the underlying health problem (file missing/unreadable/invalid) so an OK snapshot can legitimately carry the data","In caching code, drop the parsed table whenever the health status downgrades"],"exampleFix":"// before\nTomlSnapshot(name=\"tools\", status=failed_status, data=parsed_table)\n// after\nTomlSnapshot(name=\"tools\", status=failed_status, data={})","handlingStrategy":"type-guard","validationCode":"from deepagents_code.configuration.types import TomlSnapshot, ProviderHealth\n\ndef safe_snapshot(name: str, status, data: dict) -> TomlSnapshot:\n    healthy = status.health is ProviderHealth.OK\n    return TomlSnapshot(name=name, status=status, data=data if healthy else {})","typeGuard":"def is_consistent_snapshot(snap: TomlSnapshot) -> bool:\n    from deepagents_code.configuration.types import ProviderHealth\n    return snap.status.health is ProviderHealth.OK or not snap.data","tryCatchPattern":"try:\n    snap = TomlSnapshot(name=name, status=status, data=data)\nexcept ValueError as exc:\n    if \"must carry no data\" in str(exc):\n        snap = TomlSnapshot(name=name, status=status, data={})\n    else:\n        raise","preventionTips":["Only attach parsed data when health is OK (use from_table on healthy reads)","Clear cached tables whenever a snapshot's health downgrades","Keep the invariant in test fixtures: non-OK status => empty data"],"tags":["invariant","configuration","toml","state-consistency"],"backgroundTag":"inconsistent-state-snapshot","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}