{"record":{"id":"e0c6125f56480d83","repo":"openzipkin/zipkin","slug":"could-not-load-lens-ui-from-lensindexhtml","errorCode":null,"errorMessage":"Could not load Lens UI from {lensIndexHtml}","messagePattern":"Could not load Lens UI from (.+?)","errorType":"exception","errorClass":"BeanCreationException","httpStatus":null,"severity":"error","filePath":"zipkin-server/src/main/java/zipkin2/server/internal/ui/ZipkinUiConfiguration.java","lineNumber":68,"sourceCode":" * <p>This includes a hard-coded cache policy, consistent with zipkin-scala.\n * <ul>\n *   <li>1 minute for index.html</li>\n *   <li>10 minute for /config.json</li>\n *   <li>365 days for hashed resources (ex /app-e12b3bbb7e5a572f270d.min.js)</li>\n * </ul>\n * Since index.html links to hashed resource names, any change to it will orphan old resources.\n * That's why hashed resource age can be 365 days.\n */\n@EnableConfigurationProperties({ZipkinUiProperties.class, CompressionProperties.class})\n@ConditionalOnProperty(name = \"zipkin.ui.enabled\", matchIfMissing = true)\npublic class ZipkinUiConfiguration {\n  @Autowired ZipkinUiProperties ui;\n  @Value(\"classpath:zipkin-lens/index.html\") Resource lensIndexHtml;\n\n  @Bean HttpService indexService() throws Exception {\n    HttpService lensIndex = maybeIndexService(ui.getBasepath(), lensIndexHtml);\n    if (lensIndex != null) return lensIndex;\n    throw new BeanCreationException(\"Could not load Lens UI from \" + lensIndexHtml);\n  }\n\n  @Bean ArmeriaServerConfigurator uiServerConfigurator(\n    HttpService indexService,\n    Optional<MeterRegistry> meterRegistry\n  ) throws IOException {\n    ServerCacheControl maxAgeYear =\n      ServerCacheControl.builder().maxAgeSeconds(TimeUnit.DAYS.toSeconds(365)).build();\n\n    HttpService uiFileService = FileService.builder(getClass().getClassLoader(), \"zipkin-lens\")\n      .cacheControl(maxAgeYear)\n      .build();\n\n    String config = writeConfig(ui);\n    return sb -> {\n      sb.service(\"/zipkin/config.json\", HttpFile.builder(HttpData.ofUtf8(config))\n        .cacheControl(ServerCacheControl.builder().maxAgeSeconds(600).build())\n        .contentType(MediaType.JSON_UTF_8)","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/openzipkin/zipkin/blob/878ce2a1fad54ca941d17fdcf2e1d924b148eb1f/zipkin-server/src/main/java/zipkin2/server/internal/ui/ZipkinUiConfiguration.java#L50-L86","documentation":"ZipkinUiConfiguration.indexService throws BeanCreationException ('Could not load Lens UI from {lensIndexHtml}') when the classpath resource zipkin-lens/index.html cannot be loaded into an HttpService. The UI assets are bundled in the server jar (or the 'slim' build expects them externally); if the resource is missing or unreadable, the UI bean cannot be created and Spring startup of that context fails.","triggerScenarios":"Running the slim Zipkin server build (which excludes bundled UI assets) without providing the lens assets on the classpath; a corrupted or repackaged jar that dropped zipkin-lens/index.html; or a custom build that excluded the resource.","commonSituations":"Using zipkin-slim.jar (no UI) but expecting the UI; shadow/fat-jar repackaging that fails to merge classpath resources; deploying zipkin-server with a broken overlay; classloader issues in some app servers.","solutions":["If you need the UI, use the full zipkin-server jar instead of the slim build","Set zipkin.ui.enabled=false when running headless/slim builds so the UI bean is not created","If repackaging, verify zipkin-lens/index.html is present on the runtime classpath (unzip -l jar | grep zipkin-lens)"],"exampleFix":"# before\njava -jar zipkin-slim.jar # expects bundled UI, throws\n\n# after\n# option 1: full build\njava -jar zipkin.jar\n# option 2: disable UI on slim build\nZIPKIN_UI_ENABLED=false java -jar zipkin-slim.jar","handlingStrategy":"fallback","validationCode":"// verify UI assets exist before enabling the UI\nnew ClassPathResource(\"zipkin-lens/index.html\").exists();","typeGuard":null,"tryCatchPattern":"catch (BeanCreationException e) when message contains 'Lens UI' -> run the full jar or set zipkin.ui.enabled=false and restart","preventionTips":["Pin deployments to the full zipkin-server jar when the UI is required","In slim/headless deployments always set zipkin.ui.enabled=false explicitly"],"tags":["zipkin","ui","lens","classpath","startup"],"backgroundTag":null,"analyzedSha":"878ce2a1fad54ca941d17fdcf2e1d924b148eb1f","analyzedAt":"2026-08-14T15:17:09.895Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}