gatsbyjs/gatsby · error

Unable to parse JSON: ${hint}

Error message

Unable to parse JSON: ${hint}

What it means

Thrown by gatsby-transformer-json's onCreateNode when JSON.parse fails on content loaded from a node whose mediaType is 'application/json'. Gatsby reads the raw file content and attempts to parse it into a JavaScript object to create GraphQL nodes; if the content is syntactically invalid JSON, the parse throws and this error wraps it with a hint identifying the offending file path or node id.

Source

Thrown at packages/gatsby-transformer-json/src/gatsby-node.js:55

    }
    if (obj.id) {
      jsonNode[`jsonId`] = obj.id
    }
    await createNode(jsonNode)
    createParentChildLink({ parent: node, child: jsonNode })
  }

  const { createNode, createParentChildLink } = actions

  const content = await loadNodeContent(node)
  let parsedContent
  try {
    parsedContent = JSON.parse(content)
  } catch {
    const hint = node.absolutePath
      ? `file ${node.absolutePath}`
      : `in node ${node.id}`
    throw new Error(`Unable to parse JSON: ${hint}`)
  }

  if (_.isArray(parsedContent)) {
    for (let i = 0, l = parsedContent.length; i < l; i++) {
      const obj = parsedContent[i]

      await transformObject(
        obj,
        createNodeId(`${node.id} [${i}] >>> JSON`),
        getType({ node, object: obj, isArray: true })
      )
    }
  } else if (_.isPlainObject(parsedContent)) {
    await transformObject(
      parsedContent,
      createNodeId(`${node.id} >>> JSON`),
      getType({ node, object: parsedContent, isArray: false })
    )

View on GitHub (pinned to 8b06340921)

Solutions

1. Open the file path reported in the hint and run it through a JSON validator (e.g. `node -e "JSON.parse(require('fs').readFileSync('PATH','utf8'))"`) to locate the exact syntax error.
2. Fix the JSON syntax: remove comments, use double quotes for keys and string values, remove trailing commas, ensure no unescaped control characters.
3. If the file intentionally uses JSON5/JSONC, configure the source plugin to not set mediaType to 'application/json', or pre-process the file into valid JSON before Gatsby reads it.
4. If the file is generated by a CMS or external process, ensure the write completes atomically before the Gatsby build starts.

Example fix

// before (broken data.json)
{
  'title': 'Hello', // single quotes + comment
  'items': [1, 2,],
}
// after
{
  "title": "Hello",
  "items": [1, 2]
}

// Validate JSON before Gatsby processes it (pre-build script)
const fs = require('fs')
const path = require('path')

function validateJsonFiles(dir) {
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name)
    if (entry.isDirectory()) validateJsonFiles(full)
    else if (entry.name.endsWith('.json')) {
      try {
        JSON.parse(fs.readFileSync(full, 'utf8'))
      } catch (e) {
        console.error(`Invalid JSON in ${full}: ${e.message}`)
        process.exit(1)
      }
    }
  }
}
validateJsonFiles('src/data')

When it happens

Trigger: A file with .json extension (or any source plugin node with mediaType 'application/json') contains a syntax error: trailing commas, unquoted keys, single-quoted strings, comments, or truncated/corrupt content. The error fires during 'gatsby build' or 'gatsby develop' in the source/transform node phase.

Common situations: JSON files with comments (e.g. tsconfig-style JSON), single-quoted strings inherited from JS config files, BOM characters, trailing commas from hand-editing, files partially written by a CMS or CI pipeline, or a non-JSON file (e.g. .json5, .jsonc) being picked up because the source plugin sets mediaType to application/json.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• Remote file node is null
• json-file-store failed to JSON.parse this string: `${dataStr

AI-assisted analysis of gatsbyjs/gatsby@8b06340921 (2026-08-13). Data as JSON: /api/errors/8a9331fbf5a6a16c. Report an issue: GitHub.