apache/iceberg · error · IllegalArgumentException

Unrecognized HTTP client type ${httpClientType}

Error message

Unrecognized HTTP client type ${httpClientType}

What it means

AwsClientFactories.configureHttpClientBuilder selects an AWS SDK HTTP client implementation based on the configured client type. Only 'urlconnection' and 'apache' are recognized; any other value for the HTTP client type property falls through the switch's default branch and throws this IllegalArgumentException. This is a configuration error surfaced at client factory construction time.

Source

Thrown at aws/src/main/java/org/apache/iceberg/aws/AwsClientFactories.java:205

   * Build a httpClientBuilder object
   *
   * @deprecated Not for public use. To configure the httpClient for a client, please use {@link
   *     HttpClientProperties#applyHttpClientConfigurations(AwsSyncClientBuilder)}. It will be
   *     removed in 2.0.0
   */
  @Deprecated
  public static SdkHttpClient.Builder configureHttpClientBuilder(String httpClientType) {
    String clientType = httpClientType;
    if (Strings.isNullOrEmpty(clientType)) {
      clientType = HttpClientProperties.CLIENT_TYPE_DEFAULT;
    }
    switch (clientType) {
      case HttpClientProperties.CLIENT_TYPE_URLCONNECTION:
        return UrlConnectionHttpClient.builder();
      case HttpClientProperties.CLIENT_TYPE_APACHE:
        return ApacheHttpClient.builder();
      default:
        throw new IllegalArgumentException("Unrecognized HTTP client type " + httpClientType);
    }
  }

  /**
   * Configure the endpoint setting for a client
   *
   * @deprecated Not for public use. To configure the endpoint for a client, please use {@link
   *     S3FileIOProperties#applyEndpointConfigurations(S3BaseClientBuilder)}, {@link
   *     AwsProperties#applyGlueEndpointConfigurations(GlueClientBuilder)}, or {@link
   *     AwsProperties#applyDynamoDbEndpointConfigurations(DynamoDbClientBuilder)}, or {@link
   *     AwsProperties#applyKmsEndpointConfigurations(KmsClientBuilder)} accordingly. It will be
   *     removed in 2.0.0
   */
  @Deprecated
  public static <T extends SdkClientBuilder> void configureEndpoint(T builder, String endpoint) {
    if (endpoint != null) {
      builder.endpointOverride(URI.create(endpoint));
    }

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Set client.type to exactly 'urlconnection' or 'apache' (values of HttpClientProperties.CLIENT_TYPE_URLCONNECTION / CLIENT_TYPE_APACHE).
2. If you intended a different AWS SDK HTTP client (netty, aws-crt), remove the property or implement a custom S3FileIOAwsClientFactory, since those are not supported by the built-in factory.
3. Ensure the corresponding SDK module (url-connection-client or apache-client) is on the classpath; then rebuild the client factory.

Example fix

// before
Map<String, String> props = Map.of("client.type", "netty");
// after
Map<String, String> props = Map.of("client.type", HttpClientProperties.CLIENT_TYPE_APACHE);

String type = props.get("client.type");
if (type != null && !type.equals("urlconnection") && !type.equals("apache")) {
  throw new IllegalArgumentException("client.type must be 'urlconnection' or 'apache', got: " + type);
}

try {
  factory = AwsClientFactories.from(props);
} catch (IllegalArgumentException e) {
  LOG.error("Bad HTTP client type config: {}", e.getMessage());
  throw e;
}

When it happens

Trigger: Setting client.type (HttpClientProperties.HTTP_CLIENT_TYPE) to any value other than 'urlconnection' or 'apache' — e.g. 'url-connection', 'URLCONNECTION', 'java11', 'netty', or a typo — then building a client via AwsClientFactories with that configuration.

Common situations: Typos or wrong casing in catalog/S3 FileIO configuration properties; copying config from docs for the AWS SDK's other HTTP implementations (netty, aws-crt) which Iceberg's aws module does not wire up; stale configs after renaming the property value.

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

• Unrecognized HTTP client type ${httpClientType}
• Cannot initialize AwsClientFactory, missing no-arg construct
• Cannot initialize AwsClientFactory, %s does not implement Aw
• Cannot acquire closed HTTP client: ${clientKey}
• Cannot create %s to generate and configure the http client b

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/3277e8439610431f. Report an issue: GitHub.