{"record":{"id":"0c6868de46936d92","repo":"ComposioHQ/composio","slug":"cannot-resolve-ref-pointer-0c6868","errorCode":null,"errorMessage":"Cannot resolve $ref ${pointer}","messagePattern":"Cannot resolve \\$ref (.+?)","errorType":"exception","errorClass":"JsonSchemaRefResolutionError","httpStatus":null,"severity":"error","filePath":"ts/packages/core/src/utils/jsonSchema.ts","lineNumber":149,"sourceCode":"  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\n * left untouched. Cycles are broken with `{ type: 'object',\n * additionalProperties: true }`. The input is never mutated.\n *\n * By default, unresolved internal refs throw `JsonSchemaRefResolutionError`.\n * Pass `{ onUnresolved: 'sentinel' }` to replace the offending node with the","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/ComposioHQ/composio/blob/64b1b85502b1beeb2379e6c9e8bf1104504fa637/ts/packages/core/src/utils/jsonSchema.ts#L131-L167","documentation":"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).","triggerScenarios":"Schema contains '#/definitions/Missing' where 'definitions.Missing' is absent, or a chained ref whose intermediate target disappeared.","commonSituations":"Partial specs where a definition was removed but references remain; typos in definition names; specs assembled by merging documents with divergent roots.","solutions":["Check the error's meta.failedAt and ref to locate the dangling pointer.","Add the missing definition or remove/inline the $ref.","Validate the schema with a JSON Schema $Ref parser before passing it to the SDK."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const ref = schema.$ref.slice(2).split('/');\nif (ref.some(k => !(schema ?? root)[k])) throw new Error('dangling ref');","typeGuard":null,"tryCatchPattern":"try { resolve(schema); } catch (e) { if (e instanceof JsonSchemaRefResolutionError && e.meta?.failedAt) {/* patch that location */} }","preventionTips":["Run a $Ref parser (e.g. @apidevtools/swagger-parser) over specs before use.","Remove refs to deleted definitions during spec cleanup."],"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"}