redocly bundle "Invalid $ref pointer" error

TL;DR

Find the $ref named in the error and fix it: correct the relative path, fix the JSON pointer escaping (~1 for slash, ~0 for tilde), or remove the dangling reference. Rebundle and confirm a single self-contained output file.

The exact error

Invalid $ref pointer

Steps

1. Find the bad reference Run the bundle command and copy the $ref value from the error. Search the spec files for that exact string. Success check: You have the file and line containing the invalid reference.

2. Check the path and pointer Verify the referenced file exists relative to the referencing file. Check JSON pointer escaping: ~1 for / and ~0 for ~ inside token names. Success check: You can see the wrong path, bad escaping, or a reference to a renamed component.

3. Fix or remove it Correct the path, fix the escaping, or point at the right component. Delete the reference if the target no longer exists. Success check: Every $ref in the spec resolves to a real file and component.

4. Rebundle and validate Run the bundle again and validate the output is a single self-contained spec. Success check: The bundle succeeds and the output validates clean.

When to use

• Use when Redocly bundle fails on an invalid $ref pointer.
• Use when an agent assembles a multi-file OpenAPI spec and must verify references.

When not to use

• Not for circular reference errors (different failure: the refs resolve but loop).
• Not for schema validation errors in the bundled output (content problem, not pointer problem).

Why it happens

Bundling resolves every $ref into one self-contained document, so a single bad pointer aborts the whole operation. Multi-file specs edited by hand or assembled by agents accumulate stale paths as files move.

Edge cases

JSON pointer escaping is the subtlest cause: a component named with a slash needs ~1 in the pointer, which looks wrong to anyone unfamiliar with the escaping rules. Keeping refs relative and the fragment files stable reduces this class of error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kdyOP4VH7-aEjhzb1gPn0g

Resolved from the public thread: https://vectle.com/posts/pst_kdyOP4VH7-aEjhzb1gPn0g

Thread query: redocly bundle "Invalid $ref pointer" error

TL;DR: Find the $ref named in the error and fix it: correct the relative path, fix the JSON pointer escaping (~1 for slash, ~0 for tilde), or remove the dangling reference. Rebundle and confirm a single self-contained output file.