gatsbyjs/gatsby · error

Unexpected cycle detected creating DocumentationJS nodes for

Error message

Unexpected cycle detected creating DocumentationJS nodes for file:

	${node.absolutePath}

For type: ${typeName}

What it means

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.

Source

Thrown at packages/gatsby-transformer-documentationjs/src/gatsby-node.js:235

  if (documentationJson && documentationJson.length > 0) {
    const handledDocs = new WeakMap()
    const typeDefs = new Map()

    const getNodeIDForType = (typeName, parent) => {
      if (typeDefs.has(typeName)) {
        return typeDefs.get(typeName)
      }

      const index = documentationJson.findIndex(
        docsJson =>
          docsJson.name === typeName &&
          [`interface`, `typedef`, `constant`].includes(docsJson.kind)
      )

      const isCycle = parent === documentationJson[index]
      if (isCycle) {
        helpers.reporter.warn(
          `Unexpected cycle detected creating DocumentationJS nodes for file:\n\n\t${node.absolutePath}\n\nFor type: ${typeName}`
        )
      }

      if (index !== -1 && !isCycle) {
        return prepareNodeForDocs(documentationJson[index], {
          commentNumber: index,
        }).node.id
      }

      return null
    }

    const tryToAddTypeDef = (type, parent) => {
      if (type.applications) {
        type.applications.forEach(t => tryToAddTypeDef(t, parent))
      }

View on GitHub (pinned to e85d62f177)

Solutions

1. Regenerate docs output — upgrade documentation.js and re-run it on the source file; newer versions handle self-referential typedefs
2. Simplify the JSDoc typedef that references itself (directly or via a circular chain) in the named file
3. If the cycle is benign, ignore the warning — only that type link is dropped, the rest of the docs build
4. Report the offending source file to the documentation.js maintainers

When it happens

Trigger: Thrown at packages/gatsby-transformer-documentationjs/src/gatsby-node.js:235 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of gatsbyjs/gatsby@e85d62f177 (2026-08-26). Data as JSON: /api/errors/329114e3f5d52b29. Report an issue: GitHub.