{"record":{"id":"d712a7c6e4278f9d","repo":"jaegertracing/jaeger","slug":"cannot-open-index-html-w","errorCode":null,"errorMessage":"cannot open index.html: %w","messagePattern":"cannot open index\\.html: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/jaeger/internal/extension/jaegerquery/internal/static_handler.go","lineNumber":198,"sourceCode":"\tout := h.indexHTMLRaw\n\tif cfg := h.getUIConfig(); cfg != nil {\n\t\tout = cfg.regexp.ReplaceAll(out, cfg.config)\n\t}\n\tversionJSON, _ := json.Marshal(version.Get())\n\tout = versionPattern.ReplaceAll(out, fmt.Appendf(nil, \"JAEGER_VERSION = %s;\", versionJSON))\n\tvar caps BackendCapabilities\n\tif h.backendCaps != nil {\n\t\tcaps = h.backendCaps(ctx)\n\t}\n\tcapsJSON, _ := json.Marshal(caps)\n\tout = capabilitiesPattern.ReplaceAll(out, fmt.Appendf(nil, \"JAEGER_BACKEND_CAPABILITIES = %s;\", capsJSON))\n\treturn out\n}\n\nfunc loadIndexHTML(open func(string) (http.File, error)) ([]byte, error) {\n\tindexFile, err := open(\"/index.html\")\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot open index.html: %w\", err)\n\t}\n\tdefer indexFile.Close()\n\tindexBytes, err := io.ReadAll(indexFile)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot read from index.html: %w\", err)\n\t}\n\treturn indexBytes, nil\n}\n\nfunc loadUIConfig(uiConfig string) (*loadedConfig, error) {\n\tif uiConfig == \"\" {\n\t\treturn nil, nil\n\t}\n\tbytesConfig, err := os.ReadFile(filepath.Clean(uiConfig))\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot read UI config file %v: %w\", uiConfig, err)\n\t}\n\tvar r []byte","sourceCodeStart":180,"sourceCodeEnd":216,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/extension/jaegerquery/internal/static_handler.go#L180-L216","documentation":"loadIndexHTML opens '/index.html' through the supplied http.FileSystem Open function and reads its contents. When Open itself fails — the file does not exist in the asset filesystem or cannot be opened — the function wraps the OS error as 'cannot open index.html'. A sibling error 'cannot read from index.html' covers failures after a successful open.","triggerScenarios":"loadIndexHTML called (from newStaticAssetsHandler at boot, or the hot-reload path) while assetsFS.Open(\"/index.html\") returns an error: the configured assets directory has no index.html at its root, the path is a directory mismatch, or permission/os errors prevent opening the file.","commonSituations":"Custom UI archives that extract to an inner folder (dist/index.html vs index.html); empty or wrongly mounted volumes in Kubernetes/Docker; SELinux or read-only mount permission issues; typos in the assets-path so http.Dir resolves to a nonexistent directory.","solutions":["Ensure index.html sits directly at the root of the configured assets directory (flatten nested dist/ folders if needed)","Check permissions on index.html and its parent directories for the user running jaeger (namei -l <path>/index.html)","If you do not need a custom UI, unset ui.assets-path so the embedded UI filesystem is used","Verify the volume mount actually contains the UI files (kubectl exec / docker exec and ls the directory)"],"exampleFix":"// before: archive extracted keeping a nested folder\n/assets-path/dist/index.html  # Open(\"/index.html\") -> file does not exist\n// after\nmv assets-path/dist/* assets-path/   # /assets-path/index.html now resolvable","handlingStrategy":"validation","validationCode":"// run before configuring the assets path\nfunc canOpenIndexHTML(dir string) error {\n\tf, err := os.Open(filepath.Join(dir, \"index.html\"))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"cannot open index.html in %s: %w\", dir, err)\n\t}\n\tdefer f.Close()\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"_, err := loadIndexHTML(assetsFS.Open)\nif err != nil {\n\tvar pathErr *fs.PathError\n\tif errors.As(err, &pathErr) && errors.Is(pathErr.Err, fs.ErrNotExist) {\n\t\tlog.Fatalf(\"index.html missing under %s — check assets-path layout\", pathErr.Path)\n\t}\n\treturn err\n}","preventionTips":["Flatten extracted UI archives so index.html is at the top level of the assets directory","Ensure the jaeger process user has read permission on index.html and every parent directory","Test the volume mount in Kubernetes/Docker before rollout (ls the mounted path)","Fall back to the embedded UI (unset assets-path) if a custom UI is not strictly required"],"tags":["ui","static-files","filesystem","file-not-found","startup"],"backgroundTag":"file-not-found","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}