{"record":{"id":"329114e3f5d52b29","repo":"gatsbyjs/gatsby","slug":"unexpected-cycle-detected-creating-documentationjs","errorCode":null,"errorMessage":"Unexpected cycle detected creating DocumentationJS nodes for file:\n\n\t${node.absolutePath}\n\nFor type: ${typeName}","messagePattern":"Unexpected cycle detected creating DocumentationJS nodes for file:\n\n\t(.+?)\n\nFor type: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/gatsby-transformer-documentationjs/src/gatsby-node.js","lineNumber":235,"sourceCode":"\n  if (documentationJson && documentationJson.length > 0) {\n    const handledDocs = new WeakMap()\n    const typeDefs = new Map()\n\n    const getNodeIDForType = (typeName, parent) => {\n      if (typeDefs.has(typeName)) {\n        return typeDefs.get(typeName)\n      }\n\n      const index = documentationJson.findIndex(\n        docsJson =>\n          docsJson.name === typeName &&\n          [`interface`, `typedef`, `constant`].includes(docsJson.kind)\n      )\n\n      const isCycle = parent === documentationJson[index]\n      if (isCycle) {\n        helpers.reporter.warn(\n          `Unexpected cycle detected creating DocumentationJS nodes for file:\\n\\n\\t${node.absolutePath}\\n\\nFor type: ${typeName}`\n        )\n      }\n\n      if (index !== -1 && !isCycle) {\n        return prepareNodeForDocs(documentationJson[index], {\n          commentNumber: index,\n        }).node.id\n      }\n\n      return null\n    }\n\n    const tryToAddTypeDef = (type, parent) => {\n      if (type.applications) {\n        type.applications.forEach(t => tryToAddTypeDef(t, parent))\n      }\n","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/gatsbyjs/gatsby/blob/e85d62f1779e353eaac1753211629a26d123e26c/packages/gatsby-transformer-documentationjs/src/gatsby-node.js#L217-L253","documentation":"Cycle guard in gatsby-transformer-documentationjs: while resolving a referenced type (typedef/interface/constant) to its DocumentationJS node id, the resolved node turned out to be its own parent (parent === documentationJson[index]), i.e. the documentation output is self-referential. The transformation warns and skips that link instead of recursing forever.","triggerScenarios":"Thrown at packages/gatsby-transformer-documentationjs/src/gatsby-node.js:235 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Regenerate docs output — upgrade documentation.js and re-run it on the source file; newer versions handle self-referential typedefs","Simplify the JSDoc typedef that references itself (directly or via a circular chain) in the named file","If the cycle is benign, ignore the warning — only that type link is dropped, the rest of the docs build","Report the offending source file to the documentation.js maintainers"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"e85d62f1779e353eaac1753211629a26d123e26c","analyzedAt":"2026-08-26T17:50:09.662Z","contentChangedAt":"2026-08-26T17:50:09.662Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}