openzipkin/zipkin · error · BeanCreationException

Could not load Lens UI from {lensIndexHtml}

Error message

Could not load Lens UI from {lensIndexHtml}

What it means

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.

Source

Thrown at zipkin-server/src/main/java/zipkin2/server/internal/ui/ZipkinUiConfiguration.java:68

 * <p>This includes a hard-coded cache policy, consistent with zipkin-scala.
 * <ul>
 *   <li>1 minute for index.html</li>
 *   <li>10 minute for /config.json</li>
 *   <li>365 days for hashed resources (ex /app-e12b3bbb7e5a572f270d.min.js)</li>
 * </ul>
 * Since index.html links to hashed resource names, any change to it will orphan old resources.
 * That's why hashed resource age can be 365 days.
 */
@EnableConfigurationProperties({ZipkinUiProperties.class, CompressionProperties.class})
@ConditionalOnProperty(name = "zipkin.ui.enabled", matchIfMissing = true)
public class ZipkinUiConfiguration {
  @Autowired ZipkinUiProperties ui;
  @Value("classpath:zipkin-lens/index.html") Resource lensIndexHtml;

  @Bean HttpService indexService() throws Exception {
    HttpService lensIndex = maybeIndexService(ui.getBasepath(), lensIndexHtml);
    if (lensIndex != null) return lensIndex;
    throw new BeanCreationException("Could not load Lens UI from " + lensIndexHtml);
  }

  @Bean ArmeriaServerConfigurator uiServerConfigurator(
    HttpService indexService,
    Optional<MeterRegistry> meterRegistry
  ) throws IOException {
    ServerCacheControl maxAgeYear =
      ServerCacheControl.builder().maxAgeSeconds(TimeUnit.DAYS.toSeconds(365)).build();

    HttpService uiFileService = FileService.builder(getClass().getClassLoader(), "zipkin-lens")
      .cacheControl(maxAgeYear)
      .build();

    String config = writeConfig(ui);
    return sb -> {
      sb.service("/zipkin/config.json", HttpFile.builder(HttpData.ofUtf8(config))
        .cacheControl(ServerCacheControl.builder().maxAgeSeconds(600).build())
        .contentType(MediaType.JSON_UTF_8)

View on GitHub (pinned to 878ce2a1fa)

Solutions

1. If you need the UI, use the full zipkin-server jar instead of the slim build
2. Set zipkin.ui.enabled=false when running headless/slim builds so the UI bean is not created
3. If repackaging, verify zipkin-lens/index.html is present on the runtime classpath (unzip -l jar | grep zipkin-lens)

Example fix

# before
java -jar zipkin-slim.jar # expects bundled UI, throws

# after
# option 1: full build
java -jar zipkin.jar
# option 2: disable UI on slim build
ZIPKIN_UI_ENABLED=false java -jar zipkin-slim.jar

// verify UI assets exist before enabling the UI
new ClassPathResource("zipkin-lens/index.html").exists();

catch (BeanCreationException e) when message contains 'Lens UI' -> run the full jar or set zipkin.ui.enabled=false and restart

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No valid endpoints found in ES hosts: {hosts}
• credential refresh thread didn't start
• Session initialization failed. See server logs
• schema not installed: apply %s, or set CASSANDRA_ENSURE_SCHE
• No nodes in the cluster

AI-assisted analysis of openzipkin/zipkin@878ce2a1fa (2026-08-14). Data as JSON: /api/errors/e0c6125f56480d83. Report an issue: GitHub.