Could not find the file specified in the Link header `${head

Error message

Could not find the file specified in the Link header `${header}`.The gatsby-plugin-gatsby-cloud is looking for a matching file (with or without a webpack hash). Check the public folder and your gatsby-config.js to ensure you are pointing to a public file.

What it means

Thrown by `transformLink` in gatsby-plugin-gatsby-cloud's build-headers-program (build-headers-program.js:55). During Gatsby's build, the plugin rewrites `Link:` HTTP header entries so they point at the webpack-hashed asset filename from the build manifest. If the referenced file is neither in the manifest nor on disk in the public folder, the transform aborts the build.

Source

Thrown at deprecated-packages/gatsby-plugin-gatsby-cloud/src/build-headers-program.js:67

  })
  Object.keys(userHeaders).forEach(path => {
    if (!merged[path]) {
      merged[path] = userHeaders[path]
    }
  })
  return merged
}

function transformLink(manifest, publicFolder, pathPrefix) {
  return header =>
    header.replace(LINK_REGEX, (__, prefix, file, suffix) => {
      const hashed = manifest[file]
      if (hashed) {
        return `${prefix}${pathPrefix}${hashed}${suffix}`
      } else if (existsSync(publicFolder(file))) {
        return `${prefix}${pathPrefix}${file}${suffix}`
      } else {
        throw new Error(
          `Could not find the file specified in the Link header \`${header}\`.` +
            `The gatsby-plugin-gatsby-cloud is looking for a matching file (with or without a ` +
            `webpack hash). Check the public folder and your gatsby-config.js to ensure you are ` +
            `pointing to a public file.`
        )
      }
    })
}

// program methods

const mapUserLinkHeaders =
  ({ manifest, pathPrefix, publicFolder }) =>
  headers =>
    _.mapValues(headers, headerList =>
      _.map(headerList, transformLink(manifest, publicFolder, pathPrefix))
    )

View on GitHub (pinned to 8b06340921)

Solutions

Open the public/ folder after a build and verify each file referenced in your `Link` headers exists.
Correct the filename/path in the `link` headers config in gatsby-config.js.
If the asset is webpack-emitted, let the plugin resolve the hash from the manifest — reference the un-hashed logical name exactly as it appears in the build output.
Ensure pathPrefix matches between header config and the build.

Example fix

// before — file does not exist in public/
{
  resolve: `gatsby-plugin-gatsby-cloud`,
  options: { headers: { '/*': [`</css/main.css>; as=style; rel=preload`] } }
}

// after — match the actual emitted filename
{
  resolve: `gatsby-plugin-gatsby-cloud`,
  options: { headers: { '/*': [`</styles.css>; as=style; rel=preload`] } }
}

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs')
const path = require('path')

function headersReferenceExisting(publicDir, headers) {
  const files = new Set(fs.readdirSync(publicDir))
  return Object.entries(headers).flatMap(([route, list]) =>
    list.filter(h => /<([^>]+)>/.test(h))
        .map(h => { const m = h.match(/<([^>]+)>/); return m && !files.has(m[1].replace(/^\//,'')) ? h : null })
        .filter(Boolean)
  )
}

Type guard

function isReferencedFilePresent(publicDir, headerLine) {
  const m = headerLine.match(/<([^>]+)>/)
  if (!m) return true
  const file = m[1].replace(/^\//, '')
  return fs.existsSync(path.join(publicDir, file))
}

Prevention

Run `gatsby build` once and inspect public/ before finalizing Link headers.
Reference logical (un-hashed) asset names exactly as webpack emits them.
Add a CI check that validates header-referenced files exist in public/.

When it happens

Trigger: A `Link` header in `gatsby-config.js` (via `gatsby-plugin-gatsby-cloud` options or headers config) referencing an asset that was not emitted by webpack; referencing a file with a typo; referencing an asset whose name changed between versions; headers configured before the asset is generated.

Common situations: Adding a `</css/style.css>; as=style; rel=preload` header when the file is actually at `/styles.css`; renaming a font/CSS file but not updating headers; setting headers for assets only produced in certain build modes (e.g. production-only chunks) during a develop build; stale pathPrefix configuration.

Related errors

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