{"record":{"id":"5cbf4c7e26a1ea3e","repo":"PrefectHQ/fastmcp","slug":"cannot-traverse-part-part-in-reference-ref-s","errorCode":null,"errorMessage":"Cannot traverse part '{part}' in reference '{ref_str}'","messagePattern":"Cannot traverse part '(.+?)' in reference '(.+?)'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/openapi/parser.py","lineNumber":196,"sourceCode":"                        target = target[int(part)]\n                    elif isinstance(target, BaseModel):\n                        # Check class fields first, then model_extra\n                        if part in target.__class__.model_fields:\n                            target = getattr(target, part, None)\n                        elif target.model_extra and part in target.model_extra:\n                            target = target.model_extra[part]\n                        else:\n                            # Special handling for components\n                            if part == \"components\" and hasattr(target, \"components\"):\n                                target = target.components\n                            elif hasattr(target, part):  # Fallback check\n                                target = getattr(target, part, None)\n                            else:\n                                target = None  # Part not found\n                    elif isinstance(target, dict):\n                        target = target.get(part)\n                    else:\n                        raise ValueError(\n                            f\"Cannot traverse part '{part}' in reference '{ref_str}'\"\n                        )\n\n                    if target is None:\n                        raise ValueError(\n                            f\"Reference part '{part}' not found in path '{ref_str}'\"\n                        )\n\n                # Handle nested references\n                if isinstance(target, self.reference_cls):\n                    return self._resolve_ref(target)\n\n                return target\n            except (AttributeError, KeyError, IndexError, TypeError, ValueError) as e:\n                raise ValueError(f\"Failed to resolve reference '{ref_str}': {e}\") from e\n\n        return item\n","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/openapi/parser.py#L178-L214","documentation":"While walking a local '#/...' JSON pointer, _resolve_ref reached a node that is neither a pydantic model nor a dict, so there is no way to look up the next path segment — e.g. the pointer descended into a scalar (string/int) or a list and then tried to index by name. The parser raises ValueError naming the offending part and full ref string. It almost always indicates a malformed $ref that doesn't match the actual document structure.","triggerScenarios":"A $ref like '#/components/schemas/User/properties/name' where an intermediate segment names a scalar or array (e.g. 'schemas' is a list, or 'User' resolved to a string); pointer segments that don't correspond to the document's nesting because the ref was hand-edited or generated against a different spec.","commonSituations":"Refs written for a different spec version/layout than the one being parsed; JSON-pointer syntax mistakes (using '.' instead of '/', forgetting that array elements need numeric indices); automated ref rewriting tools producing paths into the wrong subtree.","solutions":["Print the target document at that pointer and compare each segment against the real structure; fix the $ref path so every segment resolves to a dict/model.","Remember JSON pointers escape '/' in key names as '~1' and '~' as '~0' — escape keys containing slashes in schemas (e.g. 'paths/x~1users').","If the target is an array, use its numeric index in the pointer instead of a name (or restructure the spec into a keyed object).","Regenerate the spec from source so refs are produced by the framework instead of hand-maintained.","Validate the document with openapi-spec-validator, which catches malformed $ref pointers before parsing."],"exampleFix":"// before\n$ref: '#/components/responses/400/content/application~1json/schema'\n\n// after  (verify segment-by-segment; '400' must actually be a key there)\n$ref: '#/components/responses/BadRequest/content/application~1json/schema'","handlingStrategy":"validation","validationCode":"import json\n\ndef check_ref_pointer(spec: dict, ref: str) -> bool:\n    if not ref.startswith(\"#/\"):\n        return False\n    target = spec\n    for part in ref[2:].split(\"/\"):\n        part = part.replace(\"~1\", \"/\").replace(\"~0\", \"~\")\n        if not isinstance(target, dict) or part not in target:\n            return False\n        target = target[part]\n    return True\n\nrefs = [r for r in walk_refs(spec)]\nbad = [r for r in refs if not check_ref_pointer(spec, r)]\nassert not bad, f\"Pointers don't match document structure: {bad}\"","typeGuard":"def resolvable_pointer(doc: dict, ref: str) -> bool:\n    if not (isinstance(ref, str) and ref.startswith(\"#/\")):\n        return False\n    node = doc\n    for part in ref[2:].split(\"/\"):\n        if not isinstance(node, dict) or part not in node:\n            return False\n        node = node[part]\n    return True","tryCatchPattern":"try:\n    routes = parse_openapi_to_http_routes(spec)\nexcept ValueError as e:\n    if \"Cannot traverse part\" in str(e):\n        logger.error(\"Malformed $ref pointer: %s\", e)\n        raise SystemExit(\"Fix the ref path to match the document nesting\") from e\n    raise","preventionTips":["Escape '/' and '~' in JSON-pointer key names (~1, ~0).","Use numeric indices when pointing into arrays.","Never hand-edit ref paths without walking the document alongside.","Validate with openapi-spec-validator, which checks ref structure."],"tags":["openapi","references","json-pointer"],"backgroundTag":"unresolved-openapi-ref","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}