{"record":{"id":"6b3ef39c68aaf757","repo":"ComposioHQ/composio","slug":"unsupported-ref-pointer-pointer-6b3ef3","errorCode":null,"errorMessage":"Unsupported $ref pointer: ${pointer}","messagePattern":"Unsupported \\$ref pointer: (.+?)","errorType":"exception","errorClass":"JsonSchemaRefResolutionError","httpStatus":null,"severity":"error","filePath":"ts/packages/core/src/utils/jsonSchema.ts","lineNumber":144,"sourceCode":"  if (!pointer.startsWith('#/')) {\n    return { kind: 'unresolved', reason: 'malformed-pointer' };\n  }\n  const segments = pointer.slice(2).split('/').map(decodePointerSegment);\n  let cursor: unknown = root;\n  for (const seg of segments) {\n    const step = tryStep(cursor, seg);\n    if (step.kind === 'unresolved') return step;\n    cursor = step.value;\n  }\n  return { kind: 'ok', value: cursor };\n};\n\nconst throwResolutionError = (\n  pointer: string,\n  result: Extract<ResolutionResult, { kind: 'unresolved' }>\n): never => {\n  if (result.reason === 'malformed-pointer') {\n    throw new JsonSchemaRefResolutionError(`Unsupported $ref pointer: ${pointer}`, {\n      meta: { ref: pointer },\n      possibleFixes: REF_RESOLUTION_FIXES,\n    });\n  }\n  throw new JsonSchemaRefResolutionError(`Cannot resolve $ref ${pointer}`, {\n    meta: {\n      ref: pointer,\n      ...(result.failedAt !== undefined ? { failedAt: result.failedAt } : {}),\n    },\n    possibleFixes: REF_RESOLUTION_FIXES,\n  });\n};\n\n/**\n * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy\n * `#/definitions/...`) so the returned schema can be safely handed to\n * consumers that don't tolerate unresolved references (e.g. AJV in\n * `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are","sourceCodeStart":126,"sourceCodeEnd":162,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/core/src/utils/jsonSchema.ts#L126-L162","documentation":"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.","triggerScenarios":"A tool's parameter schema contains refs like '#definitions/Foo' (missing slash), 'definitions/Foo' (missing #/), or JSON Pointer escapes that are malformed.","commonSituations":"Consuming third-party OpenAPI specs whose refs don't follow the '#/...' convention; backend tools generated from specs with non-standard $ref formats.","solutions":["Normalize refs to canonical '#/path/to/definition' form in the source schema.","External URLs in $ref are intentionally left untouched — check the log warning; only malformed pointers throw.","If you control the tool definition, fix the $ref strings in the OpenAPI spec."],"exampleFix":"// before\n{ \"$ref\": \"definitions/Foo\" }\n// after\n{ \"$ref\": \"#/definitions/Foo\" }","handlingStrategy":"validation","validationCode":"const okRef = (r: string) => r.startsWith('#/') || /^[a-z]+:\\/\\//i.test(r);","typeGuard":"const isWellFormedRef = (r: string): boolean => r.startsWith('#/') || /^https?:\\/\\//.test(r);","tryCatchPattern":"try { normalize(schema); } catch (e) { if (e instanceof JsonSchemaRefResolutionError) {/* fix refs listed in e.meta */} }","preventionTips":["Lint $ref values in OpenAPI specs in CI.","Normalize to '#/...' canonical form when generating schemas."],"tags":["json-schema","ref-resolution","typescript"],"backgroundTag":"json-schema-ref-resolution-failed","analyzedSha":"64b1b85502b1beeb2379e6c9e8bf1104504fa637","analyzedAt":"2026-08-28T15:39:33.623Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}