ComposioHQ/composio · error · JsonSchemaRefResolutionError

Unsupported $ref pointer: ${pointer}

Error message

Unsupported $ref pointer: ${pointer}

What it means

During JSON Schema $ref resolution, a pointer that does not start with '#/' (or is otherwise not a valid JSON Pointer) is classified as malformed and throws JsonSchemaRefResolutionError with possible fixes attached.

Source

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

  if (!pointer.startsWith('#/')) {
    return { kind: 'unresolved', reason: 'malformed-pointer' };
  }
  const segments = pointer.slice(2).split('/').map(decodePointerSegment);
  let cursor: unknown = root;
  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

View on GitHub (pinned to 64b1b85502)

Solutions

1. Normalize refs to canonical '#/path/to/definition' form in the source schema.
2. External URLs in $ref are intentionally left untouched — check the log warning; only malformed pointers throw.
3. If you control the tool definition, fix the $ref strings in the OpenAPI spec.

Example fix

// before
{ "$ref": "definitions/Foo" }
// after
{ "$ref": "#/definitions/Foo" }

const okRef = (r: string) => r.startsWith('#/') || /^[a-z]+:\/\//i.test(r);

const isWellFormedRef = (r: string): boolean => r.startsWith('#/') || /^https?:\/\//.test(r);

try { normalize(schema); } catch (e) { if (e instanceof JsonSchemaRefResolutionError) {/* fix refs listed in e.meta */} }

When it happens

Trigger: A tool's parameter schema contains refs like '#definitions/Foo' (missing slash), 'definitions/Foo' (missing #/), or JSON Pointer escapes that are malformed.

Common situations: Consuming third-party OpenAPI specs whose refs don't follow the '#/...' convention; backend tools generated from specs with non-standard $ref formats.

Related errors

• Cannot resolve $ref ${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/6b3ef39c68aaf757. Report an issue: GitHub.