gatsbyjs/gatsby · error

\nWe were unable to find the declaration of variable "${varN

Error message

\nWe were unable to find the declaration of variable "${varName}", which you passed as the "query" prop into the ${usageFunction} declaration in "${file}".\n\nPerhaps the variable name has a typo?\n\nAlso note that we are currently unable to use queries defined in files other than the file where the ${usageFunction} is defined. If you're attempting to import the query, please move it into "${file}". If being able to import queries from another file is an important capability for you, we invite your help fixing it.\n

What it means

warnForUnknownQueryVariable fires during query extraction when a page/staticQuery/useStaticQuery call receives a `query` prop referencing a variable Gatsby cannot find a declaration for in the same file. Either the variable name is misspelled/undefined or the query is imported from another file, which Gatsby's static extractor cannot follow.

Source

Thrown at packages/gatsby/src/query/file-parser.js:105

  if (callee.type === `MemberExpression`) {
    const property = callee.property
    if (property.name === `useStaticQuery`) {
      return referencesGatsby(
        path,
        path.get(`callee`).get(`object`),
        path.node?.callee.object.name
      )
    }
    return false
  }
  if (callee.name === `useStaticQuery`) {
    return referencesGatsby(path, path.get(`callee`), path.node?.callee.name)
  }
  return false
}

const warnForUnknownQueryVariable = (varName, file, usageFunction) =>
  report.warn(
    `\nWe were unable to find the declaration of variable "${varName}", which you passed as the "query" prop into the ${usageFunction} declaration in "${file}".

Perhaps the variable name has a typo?

Also note that we are currently unable to use queries defined in files other than the file where the ${usageFunction} is defined. If you're attempting to import the query, please move it into "${file}". If being able to import queries from another file is an important capability for you, we invite your help fixing it.\n`
  )

async function parseToAst(filePath, fileStr, { parentSpan, addError } = {}) {
  let ast

  // Since gatsby-plugin-mdx v4, we are using the resourceQuery feature of webpack's loaders to inject a content file into a page component.
  const cleanFilePath = getPathToLayoutComponent(filePath)

  // Preprocess and attempt to parse source; return an AST if we can, log an
  // error if we can't.
  const transpiled = await apiRunnerNode(`preprocessSource`, {
    filename: cleanFilePath,
    contents: fileStr,

View on GitHub (pinned to e85d62f177)

Solutions

1. Fix the typo in the variable name passed as the query prop
2. Declare the query string in the same file as the page/useStaticQuery call
3. Inline the GraphQL query literal instead of importing it

When it happens

Trigger: Thrown at packages/gatsby/src/query/file-parser.js:105 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/42388ed62ca58629. Report an issue: GitHub.