apache/hadoop · error · RuntimeException

WebImageViewer does not support secure mode. To start in non

Error message

WebImageViewer does not support secure mode. To start in non-secure mode, pass -Dhadoop.security.authentication=simple

What it means

WebImageViewer (`hdfs oiv -p Web`, the default processor, `-addr host:port`) serves an unauthenticated read-only WebHDFS API over the fsimage and has no SPNEGO/Kerberos support. On start it checks UserGroupInformation.isSecurityEnabled() and refuses to run when the effective configuration sets hadoop.security.authentication=kerberos.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/WebImageViewer.java:86

    this.workerGroup = new NioEventLoopGroup();
    this.allChannels = new DefaultChannelGroup(GlobalEventExecutor.INSTANCE);
    this.bootstrap = new ServerBootstrap()
      .group(bossGroup, workerGroup)
      .channel(NioServerSocketChannel.class);
    this.conf = conf;
    UserGroupInformation.setConfiguration(conf);
  }

  /**
   * Start WebImageViewer and wait until the thread is interrupted.
   * @param fsimage the fsimage to load.
   * @throws IOException if failed to load the fsimage.
   * @throws RuntimeException if security is enabled in configuration.
   */
  public void start(String fsimage) throws IOException {
    try {
      if (UserGroupInformation.isSecurityEnabled()) {
        throw new RuntimeException(
            "WebImageViewer does not support secure mode. To start in " +
                "non-secure mode, pass -D" +
                CommonConfigurationKeysPublic.HADOOP_SECURITY_AUTHENTICATION +
                "=simple");
      }
      initServer(fsimage);
      channel.closeFuture().await();
    } catch (InterruptedException e) {
      LOG.info("Interrupted. Stopping the WebImageViewer.");
      close();
    }
  }

  /**
   * Start WebImageViewer.
   * @param fsimage the fsimage to load.
   * @throws IOException if fail to load the fsimage.
   */

View on GitHub (pinned to 2add963021)

Solutions

1. Force simple auth for the JVM as the message says: `HADOOP_OPTS="-Dhadoop.security.authentication=simple" hdfs oiv -p Web -i <fsimage> -addr ...`
2. Or point `hdfs --config <dir>` at a stripped conf dir whose core-site.xml sets hadoop.security.authentication=simple
3. Because the endpoint is unauthenticated, bind to localhost (-addr 127.0.0.1:port) or a trusted network only

Example fix

# before: inherits the cluster's kerberos config
hdfs oiv -p Web -i fsimage_0000000000000123456 -addr 0.0.0.0:11000
# RuntimeException: WebImageViewer does not support secure mode...

# after: force non-secure mode and bind loopback
HADOOP_OPTS="-Dhadoop.security.authentication=simple" \
  hdfs oiv -p Web -i fsimage_0000000000000123456 -addr 127.0.0.1:11000

Configuration conf = new Configuration();
conf.set(CommonConfigurationKeysPublic.HADOOP_SECURITY_AUTHENTICATION, "simple");
UserGroupInformation.setConfiguration(conf);
if (UserGroupInformation.isSecurityEnabled()) {
  throw new IllegalStateException(
      "WebImageViewer cannot start: Kerberos still enabled after forcing simple auth");
}

When it happens

Trigger: Starting the viewer in an environment whose core-site.xml (or inherited configuration) enables Kerberos — e.g. running on a secured cluster node without overriding the setting.

Common situations: Running `hdfs oiv` on a Kerberized cluster host that picks up /etc/hadoop conf; CI containers built from cluster configuration.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Failed to obtain user group information: {}
• Fetch of delegation token failed
• Security is enabled but block access tokens (via dfs.block.a
• Security enabled but user not authenticated by filter
• Usernames not matched: name={shortName} != expected={expecte

AI-assisted analysis of apache/hadoop@2add963021 (2026-08-22). Data as JSON: /api/errors/8f26b2bd3e9a57ea. Report an issue: GitHub.