PrefectHQ/fastmcp · error · ValueError

Reference part '{part}' not found in path '{ref_str}'

Error message

Reference part '{part}' not found in path '{ref_str}'

What it means

This is the 'dead end' variant of reference resolution: _resolve_ref traversed a valid-looking '#/...' pointer but at some segment the lookup returned None, meaning that part does not exist in the document at that point. The parser raises ValueError naming the missing part and full ref. It signals a dangling or stale $ref — the path syntax is fine, but the target was never defined, was renamed, or was removed.

Source

Thrown at fastmcp_slim/fastmcp/utilities/openapi/parser.py:201

                        elif target.model_extra and part in target.model_extra:
                            target = target.model_extra[part]
                        else:
                            # Special handling for components
                            if part == "components" and hasattr(target, "components"):
                                target = target.components
                            elif hasattr(target, part):  # Fallback check
                                target = getattr(target, part, None)
                            else:
                                target = None  # Part not found
                    elif isinstance(target, dict):
                        target = target.get(part)
                    else:
                        raise ValueError(
                            f"Cannot traverse part '{part}' in reference '{ref_str}'"
                        )

                    if target is None:
                        raise ValueError(
                            f"Reference part '{part}' not found in path '{ref_str}'"
                        )

                # Handle nested references
                if isinstance(target, self.reference_cls):
                    return self._resolve_ref(target)

                return target
            except (AttributeError, KeyError, IndexError, TypeError, ValueError) as e:
                raise ValueError(f"Failed to resolve reference '{ref_str}': {e}") from e

        return item

    def _extract_schema_as_dict(self, schema_obj: Any) -> JsonSchema:
        """Resolves a schema and returns it as a dictionary."""
        try:
            resolved_schema = self._resolve_ref(schema_obj)

View on GitHub (pinned to 1f02114297)

Solutions

1. Search the document for the missing key (`jq '.components.schemas | keys' spec.json`) and correct the ref's spelling/casing to match an existing key.
2. Ensure every $ref target exists after any preprocessing/pruning — run a $ref integrity checker or openapi-spec-validator on the final bundled document.
3. If components were intentionally removed, inline the definition at the ref site instead of keeping a dangling pointer.
4. Regenerate the spec from the source framework so refs and components are produced together.
5. Check for case-sensitivity mismatches ('User' vs 'user') and version drift between spec files.

Example fix

// before
$ref: '#/components/schemas/user'   # only 'User' exists

// after
$ref: '#/components/schemas/User'

import json

def dangling_refs(spec: dict) -> list[str]:
    refs = walk_all_refs(spec)  # collect every $ref string
    def exists(ref: str) -> bool:
        node = spec
        for part in ref[2:].split("/"):
            part = part.replace("~1", "/").replace("~0", "~")
            if not isinstance(node, dict) or part not in node:
                return False
            node = node[part]
        return True
    return [r for r in refs if not exists(r)]

bad = dangling_refs(spec)
assert not bad, f"Dangling refs: {bad}"

def ref_target_exists(spec: dict, ref: str) -> bool:
    if not ref.startswith("#/"):
        return False
    node: object = spec
    for part in ref[2:].split("/"):
        if isinstance(node, dict) and part in node:
            node = node[part]
        else:
            return False
    return True

try:
    routes = parse_openapi_to_http_routes(spec)
except ValueError as e:
    if "not found in path" in str(e):
        logger.error("Dangling $ref: %s", e)
        raise SystemExit("Define the missing component or fix the ref") from e
    raise

When it happens

Trigger: $ref values like '#/components/schemas/User' when components/schemas contains no 'User' key (typo, case mismatch, or the definition was removed); refs kept after stripping shared components from a spec; two specs where one references components only present in the other.

Common situations: Editing specs by hand and renaming a schema without updating refs; build tooling that prunes unused components; merging API versions (v2 spec refs pointing at v1 components); copy-pasting refs between documents.

Related errors

• Cannot traverse part '{part}' in reference '{ref_str}'
• External or non-local reference not supported: {ref_str}
• HTTP error {response.status_code}: {response.reason_phrase}
• HTTP request timed out ({type(exc).__name__})
• Request error ({type(exc).__name__}): {exc!s}

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/ebfbfff048e41e90. Report an issue: GitHub.