ComposioHQ/composio · error · JsonSchemaRefResolutionError

Cannot resolve $ref ${pointer}

Error message

Cannot resolve $ref ${pointer}

What it means

A $ref pointer was syntactically valid but could not be resolved: the referenced location does not exist in the document, or resolution failed partway (failedAt metadata records where).

Source

Thrown at ts/packages/core/src/utils/jsonSchema.ts:149

  for (const seg of segments) {
    const step = tryStep(cursor, seg);
    if (step.kind === 'unresolved') return step;
    cursor = step.value;
  }
  return { kind: 'ok', value: cursor };
};

const throwResolutionError = (
  pointer: string,
  result: Extract<ResolutionResult, { kind: 'unresolved' }>
): never => {
  if (result.reason === 'malformed-pointer') {
    throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {
      meta: { ref: pointer },
      possibleFixes: REF_RESOLUTION_FIXES,
    });
  }
  throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {
    meta: {
      ref: pointer,
      ...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),
    },
    possibleFixes: REF_RESOLUTION_FIXES,
  });
};

/**
 * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy
 * `#/definitions/...`) so the returned schema can be safely handed to
 * consumers that don't tolerate unresolved references (e.g. AJV in
 * `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are
 * left untouched. Cycles are broken with `{ type: 'object',
 * additionalProperties: true }`. The input is never mutated.
 *
 * By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.
 * Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the

View on GitHub (pinned to 64b1b85502)

Solutions

1. Check the error's meta.failedAt and ref to locate the dangling pointer.
2. Add the missing definition or remove/inline the $ref.
3. Validate the schema with a JSON Schema $Ref parser before passing it to the SDK.

const ref = schema.$ref.slice(2).split('/');
if (ref.some(k => !(schema ?? root)[k])) throw new Error('dangling ref');

try { resolve(schema); } catch (e) { if (e instanceof JsonSchemaRefResolutionError && e.meta?.failedAt) {/* patch that location */} }

When it happens

Trigger: Schema contains '#/definitions/Missing' where 'definitions.Missing' is absent, or a chained ref whose intermediate target disappeared.

Common situations: Partial specs where a definition was removed but references remain; typos in definition names; specs assembled by merging documents with divergent roots.

Related errors

• Unsupported $ref pointer: ${pointer}
• JSON Schema $ref chain exceeded depth cap (${MAX_REF_CHAIN_D
• Cannot resolve $ref {pointer}
• Dynamic-key schema reference {reference!r} must be a local J
• Unresolvable dynamic-key schema reference: {reference!r}

AI-assisted analysis of ComposioHQ/composio@64b1b85502 (2026-08-28). Data as JSON: /api/errors/0c6868de46936d92. Report an issue: GitHub.