{"id":"b96635d04d122a1e","repo":"evanw/esbuild","slug":"invalid-fallback-path-s","errorCode":null,"errorMessage":"Invalid fallback path: %s","messagePattern":"Invalid fallback path: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/api/serve_other.go","lineNumber":763,"sourceCode":"\tif (serveOptions.Keyfile != \"\") != (serveOptions.Certfile != \"\") {\n\t\treturn ServeResult{}, errors.New(\"Must specify both key and certificate for HTTPS\")\n\t}\n\n\t// Validate the \"servedir\" path\n\tif serveOptions.Servedir != \"\" {\n\t\tif absPath, ok := ctx.realFS.Abs(serveOptions.Servedir); ok {\n\t\t\tserveOptions.Servedir = absPath\n\t\t} else {\n\t\t\treturn ServeResult{}, fmt.Errorf(\"Invalid serve path: %s\", serveOptions.Servedir)\n\t\t}\n\t}\n\n\t// Validate the \"fallback\" path\n\tif serveOptions.Fallback != \"\" {\n\t\tif absPath, ok := ctx.realFS.Abs(serveOptions.Fallback); ok {\n\t\t\tserveOptions.Fallback = absPath\n\t\t} else {\n\t\t\treturn ServeResult{}, fmt.Errorf(\"Invalid fallback path: %s\", serveOptions.Fallback)\n\t\t}\n\t}\n\n\t// Validate the CORS origins\n\tfor _, origin := range serveOptions.CORS.Origin {\n\t\tif star := strings.IndexByte(origin, '*'); star >= 0 && strings.ContainsRune(origin[star+1:], '*') {\n\t\t\treturn ServeResult{}, fmt.Errorf(\"Invalid origin: %s\", origin)\n\t\t}\n\t}\n\n\t// Stuff related to the output directory only matters if there are entry points\n\toutdirPathPrefix := \"\"\n\tif len(ctx.args.entryPoints) > 0 {\n\t\t// Don't allow serving when builds are written to stdout\n\t\tif ctx.args.options.WriteToStdout {\n\t\t\twhat := \"entry points\"\n\t\t\tif len(ctx.args.entryPoints) == 1 {\n\t\t\t\twhat = \"an entry point\"","sourceCodeStart":745,"sourceCodeEnd":781,"githubUrl":"https://github.com/evanw/esbuild/blob/6ff1d8b0d8c134e867a397eef39702a223ebef9e/pkg/api/serve_other.go#L745-L781","documentation":"Returned by internalContext.Serve when serveOptions.Fallback is non-empty but ctx.realFS.Abs(Fallback) fails to absolutize it. The fallback is the file served when a request doesn't match any built output (e.g. for SPA routing); esbuild requires it to be resolvable to an absolute path. The ok check at serve_other.go:760 returns false, triggering the error.","triggerScenarios":"Calling ctx.Serve({ Fallback: './index.html' }) where the fallback path does not exist or cannot be resolved by realFS.Abs. The guard at serve_other.go:760 fails.","commonSituations":"The fallback file doesn't exist (typo, not generated yet); relative path that doesn't resolve from esbuild's cwd; pointing Fallback at a file the build will produce before the first build has run; permissions blocking stat.","solutions":["Ensure the fallback file exists and is readable before calling Serve().","Use an absolute path for Fallback to remove cwd ambiguity.","If the fallback is a build output, run an initial build first so the file exists.","Double-check the filename and extension for typos."],"exampleFix":"// before\nctx.Serve({ Servedir: './www', Fallback: './www/index.htm' }); // typo: .htm not present\n\n// after\nctx.Serve({ Servedir: './www', Fallback: path.resolve('./www/index.html') });","handlingStrategy":"validation","validationCode":"const fs = require('fs');\nif (serveOpts.Fallback) {\n  const abs = path.resolve(serveOpts.Fallback);\n  if (!fs.existsSync(abs)) throw new Error('fallback file missing');\n  serveOpts.Fallback = abs;\n}","typeGuard":"function isFallbackPathError(e) { return /Invalid fallback path/.test(e?.message || ''); }","tryCatchPattern":"try { await ctx.Serve({ Fallback }); } catch (e) { if (isFallbackPathError(e)) { /* generate or fix the fallback file, then retry */ } throw e; }","preventionTips":["Ensure the fallback file exists before Serve().","Use an absolute path for Fallback.","Run an initial build if fallback is a generated output.","Check filename and extension for typos."],"tags":["esbuild","serve","configuration","filesystem","validation"],"analyzedSha":"6ff1d8b0d8c134e867a397eef39702a223ebef9e","analyzedAt":"2026-08-03T19:42:38.433Z","schemaVersion":2}