{"record":{"id":"ac4c3b0607c4d473","repo":"jaegertracing/jaeger","slug":"cannot-load-index-html-w","errorCode":null,"errorMessage":"cannot load index.html: %w","messagePattern":"cannot load index\\.html: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/jaeger/internal/extension/jaegerquery/internal/static_handler.go","lineNumber":112,"sourceCode":"}\n\ntype loadedConfig struct {\n\tregexp *regexp.Regexp\n\tconfig []byte\n}\n\nfunc newStaticAssetsHandler(\n\tqOpts *QueryOptions,\n\tbackendCaps BackendCapabilityProvider,\n\tlogger *zap.Logger,\n) (*staticAssetsHandler, error) {\n\tassetsFS := ui.GetStaticFiles(logger)\n\tif qOpts.UIConfig.AssetsPath != \"\" {\n\t\tassetsFS = http.Dir(qOpts.UIConfig.AssetsPath)\n\t}\n\traw, err := loadIndexHTML(assetsFS.Open)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"cannot load index.html: %w\", err)\n\t}\n\th := &staticAssetsHandler{\n\t\tassetsFS:     assetsFS,\n\t\tbasePath:     qOpts.BasePath,\n\t\tlogAccess:    qOpts.UIConfig.LogAccess,\n\t\tbackendCaps:  backendCaps,\n\t\tlogger:       logger,\n\t\tindexHTMLRaw: raw,\n\t\tuiConfigFile: qOpts.UIConfig.ConfigFile,\n\t}\n\tif h.uiConfigFile != \"\" {\n\t\t// Eager initial load: surface UI-config syntax errors at startup\n\t\t// rather than letting them appear on the first page-load several\n\t\t// seconds later. Subsequent reloads are lazy, gated by uiConfigExpiry.\n\t\tcfg, err := loadUIConfig(h.uiConfigFile)\n\t\tif err != nil {\n\t\t\treturn nil, err\n\t\t}","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/jaegertracing/jaeger/blob/806f4447841ecdb60519f408b004a599d515f437/cmd/jaeger/internal/extension/jaegerquery/internal/static_handler.go#L94-L130","documentation":"newStaticAssetsHandler builds the handler that serves the Jaeger UI. It resolves the asset filesystem (embedded UI files by default, or http.Dir(AssetsPath) when ui.assets-path is set) and then reads index.html through loadIndexHTML. If reading/parsing index.html fails for any reason, construction aborts with this wrapped error so a broken UI deployment fails at startup instead of serving a broken page.","triggerScenarios":"Calling RegisterStaticHandler/newStaticAssetsHandler when loadIndexHTML fails: the configured ui.assets-path directory does not exist or contains no index.html, the file is unreadable (permissions), or it is empty/corrupt so the load step rejects it.","commonSituations":"Pointing --query.ui-config assets-path at a directory where the Jaeger UI zip was not fully extracted; a Docker volume mounted empty or at the wrong path; permission changes after a container restart; a custom UI build that forgot to emit index.html at the root of the assets directory.","solutions":["Verify the assets path: ls <assets-path>/index.html — ensure the file exists at the root of the configured directory, not in a nested subfolder","If the path is wrong, correct ui.assets-path or remove it to fall back to the UI embedded in the Jaeger binary","Fix filesystem permissions so the jaeger process can read index.html","Re-download/rebuild the custom UI and confirm index.html is present and non-empty before restarting"],"exampleFix":"// before\nquery:\n  ui:\n    assets-path: /opt/jaeger-ui/dist/assets   # index.html not here\n// after\nquery:\n  ui:\n    assets-path: /opt/jaeger-ui/dist          # directory containing index.html","handlingStrategy":"validation","validationCode":"// verify the assets path before constructing the server\nfunc validateAssetsPath(dir string) error {\n\tif dir == \"\" {\n\t\treturn nil // embedded UI is used\n\t}\n\tfi, err := os.Stat(filepath.Join(dir, \"index.html\"))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"assets path %q has no index.html: %w\", dir, err)\n\t}\n\tif fi.IsDir() || fi.Size() == 0 {\n\t\treturn fmt.Errorf(\"%q/index.html is a directory or empty\", dir)\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"handler, err := newStaticAssetsHandler(qOpts, caps, logger)\nif err != nil {\n\tvar pathErr *fs.PathError\n\tif errors.As(err, &pathErr) {\n\t\tlog.Fatalf(\"UI assets broken at %s: %v\", pathErr.Path, err)\n\t}\n\treturn err\n}","preventionTips":["Point ui.assets-path at the directory that directly contains index.html, not a nested dist/ subfolder","After extracting a custom UI zip, verify index.html exists at the root before starting jaeger","In containers, health-check the mounted volume contents (test -f /assets/index.html) at startup","Omit assets-path entirely when you want the UI embedded in the binary"],"tags":["config","ui","static-files","filesystem","startup"],"backgroundTag":"missing-index-html","analyzedSha":"806f4447841ecdb60519f408b004a599d515f437","analyzedAt":"2026-09-01T02:39:22.140Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}