{"record":{"id":"ecdf668a49a1ae12","repo":"ComposioHQ/composio","slug":"unresolvable-dynamic-key-schema-reference-refere","errorCode":null,"errorMessage":"Unresolvable dynamic-key schema reference: {reference!r}","messagePattern":"Unresolvable dynamic-key schema reference: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/composio/utils/schema_converter.py","lineNumber":360,"sourceCode":"        return root_schema\n    if not reference.startswith(\"#/\"):\n        raise ValueError(\n            f\"Dynamic-key schema reference {reference!r} must be a local JSON Pointer\"\n        )\n\n    current: t.Any = root_schema\n    for raw_token in unquote(reference[2:]).split(\"/\"):\n        token = raw_token.replace(\"~1\", \"/\").replace(\"~0\", \"~\")\n        if isinstance(current, dict) and token in current:\n            current = current[token]\n            continue\n        if isinstance(current, list):\n            try:\n                current = current[int(token)]\n                continue\n            except (ValueError, IndexError):\n                pass\n        raise ValueError(f\"Unresolvable dynamic-key schema reference: {reference!r}\")\n    return current\n\n\ndef _resolve_default_metadata_schema(\n    schema: t.Any,\n    root_schema: t.Dict[str, t.Any],\n    visited_refs: t.Optional[t.Set[str]] = None,\n) -> t.Any:\n    \"\"\"Resolve a schema node without traversing instance-valued annotations.\"\"\"\n    if not isinstance(schema, dict):\n        return schema\n    reference = schema.get(\"$ref\")\n    if not isinstance(reference, str) or not reference.startswith(\"#/\"):\n        return schema\n    if visited_refs is None:\n        visited_refs = set()\n    if reference in visited_refs:\n        return {key: value for key, value in schema.items() if key != \"$ref\"}","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/python/composio/utils/schema_converter.py#L342-L378","documentation":"The $ref is a well-formed local JSON Pointer (\"#/...\") but the pointer path does not exist in the root schema: a token doesn't match a key, or a list index is invalid/out of range. _resolve_local_json_pointer walks the tokens (applying ~0/~1 unescaping) and raises this ValueError when traversal dead-ends.","triggerScenarios":"\"$ref\": \"#/definitions/MissingName\" when definitions lacks that key; pointing into an array element that doesn't exist (\"#/items/5\"); typos in the pointer path; refs valid against a different root document than the one passed in.","commonSituations":"Renamed or removed definitions in a regenerated schema while stale refs remain; schemas copy-pasted between documents where the target was left behind; case mismatches in definition names; version skew between cached and refreshed tool schemas.","solutions":["Verify the exact token path against the root schema (check spelling/case of every key under definitions/$defs)","Re-fetch or regenerate the schema pair so refs and definitions come from the same source","If the target was renamed, update the $ref to the new location"],"exampleFix":"# before\n{\"$ref\": \"#/definitions/Usr\"}\n# after\n{\"$ref\": \"#/definitions/User\"}","handlingStrategy":"validation","validationCode":"from jsonschema import RefResolver  # or manual pointer walk\ndef pointer_resolves(ref, root):\n    if ref == \"#\": return True\n    if not ref.startswith(\"#/\"): return False\n    cur = root\n    for tok in ref[2:].split(\"/\"):\n        tok = tok.replace(\"~1\", \"/\").replace(\"~0\", \"~\")\n        if isinstance(cur, dict) and tok in cur: cur = cur[tok]\n        elif isinstance(cur, list) and tok.isdigit() and int(tok) < len(cur): cur = cur[int(tok)]\n        else: return False\n    return True","typeGuard":null,"tryCatchPattern":"try:\n    build_model(schema)\nexcept ValueError as e:\n    if \"Unresolvable\" in str(e):\n        raise ToolSchemaError(f\"stale ref in {tool.name}: {e}\") from e","preventionTips":["Keep definitions and refs in the same document/source version","Regenerate schema pairs together rather than mixing old refs with new definitions","Add a pointer-resolution pre-check in schema tests"],"tags":["json-schema","ref-resolution","json-pointer"],"backgroundTag":"unresolvable-json-schema-ref","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}