apache/hadoop · error · IOException

Unknown channel mode: {}

Error message

Unknown channel mode: {}

What it means

DelegatingSSLSocketFactory's constructor switch on SSLChannelMode hit its default branch: the enum value passed is not one of the four handled modes (OpenSSL, Default, Default_JSSE, Default_JSSE_with_GCM). Since those are all constants of the enum, this practically means the caller and this class come from different Hadoop builds — a newer SSLChannelMode constant compiled against an older factory (version/shading skew).

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/security/ssl/DelegatingSSLSocketFactory.java:182

            e);
        ctx = SSLContext.getDefault();
        channelMode = SSLChannelMode.Default_JSSE;
      }
      break;
    case OpenSSL:
      bindToOpenSSLProvider();
      channelMode = SSLChannelMode.OpenSSL;
      break;
    case Default_JSSE:
      ctx = SSLContext.getDefault();
      channelMode = SSLChannelMode.Default_JSSE;
      break;
    case Default_JSSE_with_GCM:
      ctx = SSLContext.getDefault();
      channelMode = SSLChannelMode.Default_JSSE_with_GCM;
      break;
    default:
      throw new IOException("Unknown channel mode: "
          + preferredChannelMode);
    }
  }

  /**
   * Bind to the OpenSSL provider via wildfly.
   * This MUST be the only place where wildfly classes are referenced,
   * so ensuring that any linkage problems only surface here where they may
   * be caught by the initialization code.
   */
  private void bindToOpenSSLProvider()
      throws NoSuchAlgorithmException, KeyManagementException {
    if (!openSSLProviderRegistered) {
      LOG.debug("Attempting to register OpenSSL provider");
      org.wildfly.openssl.OpenSSLProvider.register();
      openSSLProviderRegistered = true;
    }
    // Strong reference needs to be kept to logger until initialization of

View on GitHub (pinned to 2add963021)

Solutions

1. Align all Hadoop artifacts to the same version: check `mvn dependency:tree` or `hadoop classpath` for duplicate hadoop-common jars
2. Exclude the older hadoop-common from the shaded/conflicting dependency so one DelegatingSSLSocketFactory/SSLChannelMode pair is used
3. Use one of the documented mode strings (OpenSSL, Default, Default_JSSE, Default_JSSE_with_GCM) wherever the mode is configured, e.g. fs.azure.ssl.channel.mode for ABFS

Example fix

<!-- before: mixed versions, pom has hadoop-common 3.2.1 next to azure-data-lake 3.3.x -->

<!-- after -->
<dependency>
  <groupId>org.apache.hadoop</groupId>
  <artifactId>hadoop-common</artifactId>
  <version>3.3.6</version>
</dependency>
<!-- and exclude hadoop-common from transitive deps pulling an older copy -->

private static final Set<SSLChannelMode> SUPPORTED = EnumSet.of(
    SSLChannelMode.OpenSSL, SSLChannelMode.Default,
    SSLChannelMode.Default_JSSE, SSLChannelMode.Default_JSSE_with_GCM);

if (!SUPPORTED.contains(preferredMode)) {
  throw new IllegalArgumentException(
      "Unsupported SSL channel mode " + preferredMode
      + "; check hadoop artifact version alignment");
}
DelegatingSSLSocketFactory.initializeDefaultFactory(preferredMode);

try {
  DelegatingSSLSocketFactory.initializeDefaultFactory(mode);
} catch (IOException e) {
  if (e.getMessage().startsWith("Unknown channel mode")) {
    // classpath skew: fail loudly and dump hadoop-common jar versions
    throw new IllegalStateException("Mixed Hadoop versions on classpath", e);
  }
  throw e;
}

When it happens

Trigger: Passing an SSLChannelMode constant that this compiled version of DelegatingSSLSocketFactory does not know; mixed hadoop-common jars on the classpath (e.g. an ABFS/other client compiled against a newer Hadoop shading an older hadoop-common).

Common situations: Dependency conflicts after upgrading one Hadoop module; shaded JARs embedding mismatched hadoop-common versions; custom distributions reordering classpath entries.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Property %s not specified
• Unbound ${method}
• The property '{}' has not been set in the ssl configuration
• Unknown client chain certificate: {}
• Unknown server chain certificate: {}

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