{"record":{"id":"ec0169a146558bf2","repo":"PrefectHQ/fastmcp","slug":"external-or-non-local-reference-not-supported-re-ec0169","errorCode":null,"errorMessage":"External or non-local reference not supported: {ref_path}. FastMCP only supports local schema references starting with '#/'. Please include all schema definitions within the OpenAPI document.","messagePattern":"External or non-local reference not supported: (.+?)\\. FastMCP only supports local schema references starting with '#/'\\. Please include all schema definitions within the OpenAPI document\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/openapi/schemas.py","lineNumber":105,"sourceCode":"    - {\"anyOf\": [{\"$ref\": \"#/components/schemas/...\"}]}\n    - {\"allOf\": [{\"$ref\": \"#/components/schemas/...\"}]}\n    - {\"oneOf\": [{\"$ref\": \"#/components/schemas/...\"}]}\n\n    Args:\n        info: dict[str, Any]\n        description: str | None\n\n    Returns:\n        dict[str, Any]\n    \"\"\"\n    schema = info.copy()\n    if ref_path := schema.get(\"$ref\"):\n        if isinstance(ref_path, str):\n            if ref_path.startswith(\"#/components/schemas/\"):\n                schema_name = ref_path.split(\"/\")[-1]\n                schema[\"$ref\"] = f\"#/$defs/{schema_name}\"\n            elif not ref_path.startswith(\"#/\"):\n                raise ValueError(\n                    f\"External or non-local reference not supported: {ref_path}. \"\n                    f\"FastMCP only supports local schema references starting with '#/'. \"\n                    f\"Please include all schema definitions within the OpenAPI document.\"\n                )\n    elif properties := schema.get(\"properties\"):\n        if \"$ref\" in properties:\n            schema[\"properties\"] = _replace_ref_with_defs(properties)\n        else:\n            schema[\"properties\"] = {\n                prop_name: _replace_ref_with_defs(prop_schema)\n                for prop_name, prop_schema in properties.items()\n            }\n    elif item_schema := schema.get(\"items\"):\n        schema[\"items\"] = _replace_ref_with_defs(item_schema)\n    for section in [\"anyOf\", \"allOf\", \"oneOf\"]:\n        if section in schema:\n            schema[section] = [_replace_ref_with_defs(item) for item in schema[section]]\n    if additionalProperties := schema.get(\"additionalProperties\"):","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/openapi/schemas.py#L87-L123","documentation":"FastMCP's `_replace_ref_with_defs` only rewrites local component-schema refs (`#/components/schemas/...`) into JSON-Schema `$defs` refs; any `$ref` that does not start with `#/` (i.e. an external file/URL or non-local document pointer) is unsupported and raises this ValueError. The library requires all schema definitions to be inlined in the OpenAPI document it parses.","triggerScenarios":"Parsing an OpenAPI document whose schemas contain refs like `pet.yaml#/Pet`, `https://example.com/schemas/pet.json`, or `definitions.json#/Pet` — anything not beginning with `#/`.","commonSituations":"Modular/multi-file API specs assembled from multiple YAML files with file-relative refs, specs that reference schemas hosted on external URLs, or vendor docs split across documents. Very common with specs produced by design-first tools that support external refs (Swagger, Stoplight) before bundling.","solutions":["Bundle the spec into a single self-contained document before parsing (e.g. `npx @redocly/cli bundle openapi.yaml -o bundled.yaml` or swagger-cli bundle).","Replace external refs manually by copying the referenced definitions into `components/schemas` of the same document and using `#/components/schemas/...` refs.","If the tool producing the spec supports an 'inline' or 'dereference' option, enable it so all refs are local."],"exampleFix":"// before\n\"$ref\": \"./pet.yaml#/components/schemas/Pet\"\n// after (bundled, local)\n\"$ref\": \"#/components/schemas/Pet\"","handlingStrategy":"validation","validationCode":"import re\n_EXTERNAL_REF = re.compile(r'^\\$ref\":\\s*\"(?!#/)', re.M)\n\ndef has_external_refs(spec_text: str) -> bool:\n    return bool(_EXTERNAL_REF.search(spec_text))","typeGuard":"def is_local_ref(ref: object) -> bool:\n    return isinstance(ref, str) and ref.startswith(\"#/\")","tryCatchPattern":"try:\n    tools = await client.get_tools_from_openapi(spec)\nexcept ValueError as e:\n    if \"External or non-local reference\" in str(e):\n        spec = bundle_spec(spec)  # e.g. redocly bundle\n        tools = await client.get_tools_from_openapi(spec)\n    else:\n        raise","preventionTips":["Always run a bundler (redocly/swagger-cli) on multi-file specs before feeding them to FastMCP.","Enable 'inline' or 'dereference' output in whatever tool generates your spec.","Grep CI for `$ref` values not starting with `#/`."],"tags":["openapi","external-ref","schema-bundling"],"backgroundTag":"unsupported-external-ref","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}