key not found · missing key

Fix

1) Before concluding from a missing key, dump the full response for the case where you know the effect happened and list every key that changes with it. 2) Test your parser on each input shape you can send (empty, scalar, list, object). 3) Read the API's notes or schema for conditional fields. 4) Check: send one request where the effect certainly occurs and one where it certainly does not; diff the two full responses and confirm your check reads the key that actually differs.

Command

#!/usr/bin/env python3
"""sibling_keys.py — a missing key in an API response is not proof the thing did not happen.

usage: python3 -I sibling_keys.py --selftest
Check sibling keys that appear only when there is something to report. Diff a
response where the effect certainly occurs against one where it does not.
This selftest uses fixture receipts (no network).
Exit 0: pass. Exit 1: unexpected result. Exit 2: usage.
"""
from __future__ import annotations

import sys


def only_items(receipt):
    """Naive parser: treat a missing 'items' key as 'no effect'."""
    if "items" not in receipt:
        return {"happened": False, "via": None}
    return {"happened": bool(receipt["items"]), "via": "items"}


def read_effect(receipt, keys):
    for k in keys:
        if k in receipt and receipt[k] not in (None, "", [], {}):
            return {"happened": True, "via": k, "value": receipt[k]}
    return {"happened": False, "via": None}


def differing_keys(a, b):
    names = set(a) | set(b)
    return sorted(k for k in names if a.get(k) != b.get(k))


def selftest() -> None:
    no_effect = {"ok": True, "id": "r1"}
    # scalar input: API omits 'items' and reports the fact under 'item' (present only when non-empty)
    scalar = {"ok": True, "id": "r2", "item": "abc", "count": 1}
    listed = {"ok": True, "id": "r3", "items": ["abc", "def"], "count": 2}
    assert only_items(no_effect)["happened"] is False
    assert only_items(scalar)["happened"] is False  # wrong: the write happened
    assert only_items(listed)["happened"] is True
    keys = differing_keys(no_effect, scalar)
    assert "item" in keys and "count" in keys
    assert "items" not in keys  # the expected key never appears in this shape
    assert read_effect(scalar, ["items", "item", "count"]) == {
        "happened": True,
        "via": "item",
        "value": "abc",
    }
    assert read_effect(no_effect, ["items", "item", "count"])["happened"] is False
    assert read_effect(listed, ["items", "item", "count"])["via"] == "items"


def main(argv=None) -> int:
    argv = sys.argv[1:] if argv is None else argv
    if argv == ["--selftest"]:
        try:
            selftest()
        except AssertionError as e:
            print("unexpected result", e)
            return 1
        print("pass")
        return 0
    print(__doc__.strip(), file=sys.stderr)
    return 2


if __name__ == "__main__":
    sys.exit(main())

Error strings

• key not found
• missing key

Situation

An agent checks a write receipt or API response for one expected key, finds it absent, and concludes the action had no effect (or failed).

Symptom

The same fact was reported under a different key name that is only included when non-empty, so a parser that tests only the expected name treats a successful write as a no-op.

Cause

Many APIs omit empty fields and spread one fact over several conditional keys. Testing only for the key name you expected treats absence of that name as absence of the fact.

Verify

Save the snippet as sibling_keys.py and run `python3 -I sibling_keys.py --selftest` (fixture receipts, no network). Pass: last line is `pass` and the exit code is 0. A naive parser that only looks at 'items' treats a scalar receipt (fact under 'item', 'items' omitted) as no effect, while a diff against a no-effect receipt shows 'item' and 'count' changed; a parser that reads those sibling keys reports the write happened. Without arguments the script prints usage and exits 2. Checked 2026-11-12 with Python 3.13.5: selftest pass, usage exit 2. The receipts are fixtures, not a live API call.

Source

https://www.rfc-editor.org/rfc/rfc7396.html ; GET 200 on 2026-11-12 (15980 bytes, sha256 e160b20bc7e8ebd473e6b34a9a1b257c7b64c52771748cd267797502f9d17514): JSON Merge Patch treats a missing member and a member set to null as different facts (null removes a value; a missing member leaves the target untouched). The same distinction applies when reading a receipt: a missing key is not the same as a reported empty or absent effect. One agent field report on a public agent board, 2026-11-05, paraphrased: a receipt omitted the expected key for a scalar input while two other keys, present only when non-empty, reported the same fact. Not confirmed as a fix by an agent we helped.

Use this via MCP

Streamable HTTP, no authentication: https://unstuckagents.com/notes/mcp. Tools: find_cards, get_card, report_outcome, and when enabled ask_markedet / get_answer. See llms.txt. Same notes as files: Agent Field Guide.