What causes "Cannot locate bundle file: ${bundle}" in vuejs/vue?

Verify the path exists before calling createBundleRenderer: assert fs.existsSync(bundlePath).

vuejs/vue · error · Error

Cannot locate bundle file: ${bundle}

Error message

Cannot locate bundle file: ${bundle}

What it means

Thrown by createBundleRenderer when the bundle argument is an absolute path ending in .js or .json but fs.existsSync returns false. The path was deemed a file path (absolute, correct extension) but no file lives there. Distinguish from error 4 which fires only when the file exists but is unreadable/invalid.

Source

Thrown at packages/server-renderer/src/bundle-renderer/create-bundle-renderer.ts:61

    if (
      typeof bundle === 'string' &&
      /\.js(on)?$/.test(bundle) &&
      path.isAbsolute(bundle)
    ) {
      if (fs.existsSync(bundle)) {
        const isJSON = /\.json$/.test(bundle)
        basedir = basedir || path.dirname(bundle)
        bundle = fs.readFileSync(bundle, 'utf-8')
        if (isJSON) {
          try {
            // @ts-expect-error
            bundle = JSON.parse(bundle)
          } catch (e: any) {
            throw new Error(`Invalid JSON bundle file: ${bundle}`)
          }
        }
      } else {
        throw new Error(`Cannot locate bundle file: ${bundle}`)
      }
    }

    if (typeof bundle === 'object') {
      entry = bundle.entry
      files = bundle.files
      basedir = basedir || bundle.basedir
      maps = createSourceMapConsumers(bundle.maps)
      if (typeof entry !== 'string' || typeof files !== 'object') {
        throw new Error(INVALID_MSG)
      }
    } else if (typeof bundle === 'string') {
      entry = '__vue_ssr_bundle__'
      files = { __vue_ssr_bundle__: bundle }
      maps = {}
    } else {
      throw new Error(INVALID_MSG)
    }

View on GitHub (pinned to 9e88707940)

Solutions

Verify the path exists before calling createBundleRenderer: assert fs.existsSync(bundlePath).
Rebuild the SSR bundle to regenerate the file at the expected location.
If the bundle is in memory (object), pass the object directly instead of a file path.
Log the resolved absolute path and confirm it matches the actual build output.

Example fix

// before
const renderer = createBundleRenderer(path.join(__dirname, 'bundle.json'))

// after
const bundlePath = path.join(__dirname, 'bundle.json')
if (!fs.existsSync(bundlePath)) {
  throw new Error(`SSR bundle not found at ${bundlePath}; run the build first`)
}
const renderer = createBundleRenderer(bundlePath)

Defensive patterns

Strategy: validation

Validate before calling

import * as fs from 'fs'
import * as path from 'path'

function assertBundleExists(p: string): void {
  if (!path.isAbsolute(p)) throw new Error(`Bundle path must be absolute: ${p}`)
  if (!fs.existsSync(p)) throw new Error(`Bundle file not found: ${p}. Run the SSR build.`)
}

assertBundleExists(bundlePath)
createBundleRenderer(bundlePath)

Type guard

function isExistingBundlePath(p: string): boolean {
  return typeof p === 'string' && path.isAbsolute(p) && /\.js(on)?$/.test(p) && fs.existsSync(p)
}

Try / catch

try {
  createBundleRenderer(bundlePath)
} catch (e) {
  if (e.message.startsWith('Cannot locate bundle file')) {
    // trigger build, then retry once
    await buildSSRBundle()
    createBundleRenderer(bundlePath)
  } else {
    throw e
  }
}

Prevention

Validate the bundle path in your server's startup config check before SSR init.
Use a health-check endpoint that confirms the bundle exists before accepting traffic.
Store the build output path in a single config constant reused by build and server.
In Docker/CI, assert the bundle file exists as a final build step.

When it happens

Trigger: Calling createBundleRenderer with a path that is absolute and ends in .js/.json but does not exist on disk. Typical when the build output directory moved, the filename changed, or a relative path was incorrectly absolutized.

Common situations: Deployment to a server where the bundle path differs from the build machine. A typo in the path. Build artifacts were cleaned/deleted before the render server started. Using path.join with wrong base dir produces a plausible-looking but nonexistent absolute path.

Related errors

AI-assisted analysis of vuejs/vue@9e88707940 (2026-08-11). Data as JSON: /api/errors/c3b838f77edda9ce. Report an issue: GitHub.