Skip to content

fix(index): report why an external reference could not be resolved - #724

Draft
daveshanley wants to merge 1 commit into
mainfrom
fix/external-ref-fetch-error
Draft

daveshanley wants to merge 1 commit into
mainfrom
fix/external-ref-fetch-error

Conversation

@daveshanley

Copy link
Copy Markdown
Member

What

When the rolodex can't open the document behind an external $ref (a 404, a timeout, a local path with no file system), the failure was only logged. The reference error then said the component does not exist in the specification. That's misleading, and it dropped both the document location and the actual cause.

Before:

component `#/components/securitySchemes/ExternalSecurityThing` does not exist in the specification

After:

component `#/components/securitySchemes/ExternalSecurityThing` cannot be resolved: unable to fetch remote document 'https://example.com/api/openapi.json' (error 404 Not Found)

How

  • lookupRolodex keeps the open failure for each document location (refOpenErrors, a sync.Map on the index, cleared with the other reference errors).
  • missingComponentError wraps that cause into the reference error with %w, so errors.Is / errors.As still reach the original error. A reference to a component that is simply absent keeps the existing message.
  • RemoteFS fetch errors now include the HTTP status text: (error 404) becomes (error 404 Not Found).

Message changes

Code that matches on error strings will see these changes:

  • Unopenable external documents now produce component … cannot be resolved: <cause> instead of … does not exist in the specification.
  • TestIssue578HttpPrefixedLocalRefDoesNotPanic now gets the real cause in the error (remote URL 'httpdocs/pet.yaml' has no scheme, unable to fetch it), which it previously only checked in the log.
  • TestNewRemoteFS_RemoteBaseURL_Error400 now expects (error 400 Bad Request).

Tests

  • New index/missing_component_error_test.go: a local server that returns 404 for a remote $ref, and a missing local component that keeps the original message.
  • go test ./... passes (35 packages).
  • vacuum's full test suite also passes against this branch. With it, vacuum reports the 404 in the security-scheme-object-examples cases from the OpenAPI conformance suite instead of saying the component doesn't exist.

🤖 Generated with Claude Code

When the rolodex could not open the document behind an external $ref, the
failure was only logged. The reference error then claimed the component
did not exist in the specification, dropping both the document location
and the cause, such as a 404 from a remote server.

The open failure is now kept per document location and wrapped into the
reference error, so a broken remote reference reads:

  component `#/components/securitySchemes/X` cannot be resolved: unable to
  fetch remote document 'https://example.com/api/openapi.json'
  (error 404 Not Found)

References to components that are simply absent keep the original message.
Remote fetch errors also carry the HTTP status text.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 20, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (34f4d57) to head (9de58b1).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #724   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          315       315           
  Lines        39919     39927    +8     
=========================================
+ Hits         39919     39927    +8     
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant