apache/hadoop · error · IllegalArgumentException

Virtual IP for failover not found,misconfigured {}?

Error message

Virtual IP for failover not found,misconfigured {}?

What it means

ObserverReadProxyProviderWithIPFailover delegates failover to an IPFailoverProxyProvider bound to a virtual address that must be configured per nameservice at dfs.client.failover.ipfailover.virtual-address.<nameservice>. Its constructor calls conf.get(configKey); a null value throws IllegalArgumentException immediately, so the proxy provider cannot be built.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-client/src/main/java/org/apache/hadoop/hdfs/server/namenode/ha/ObserverReadProxyProviderWithIPFailover.java:137

   * @param haURI the ha uri, a name service id in this case.
   */
  private void cloneDelegationTokenForVirtualIP(
      Configuration conf, URI haURI) {
    URI virtualIPURI = getFailoverVirtualIP(conf, haURI.getHost());
    InetSocketAddress vipAddress = new InetSocketAddress(
        virtualIPURI.getHost(), virtualIPURI.getPort());
    HAUtilClient.cloneDelegationTokenForLogicalUri(
        ugi, haURI, Collections.singleton(vipAddress));
  }

  private static URI getFailoverVirtualIP(
      Configuration conf, String nameServiceID) {
    String configKey = IPFAILOVER_CONFIG_PREFIX + "." + nameServiceID;
    String virtualIP = conf.get(configKey);
    LOG.info("Name service ID {} will use virtual IP {} for failover",
        nameServiceID, virtualIP);
    if (virtualIP == null) {
      throw new IllegalArgumentException("Virtual IP for failover not found,"
          + "misconfigured " + configKey + "?");
    }
    return URI.create(virtualIP);
  }
}

View on GitHub (pinned to 2add963021)

Solutions

1. Set dfs.client.failover.ipfailover.virtual-address.<ns-id>=hdfs://<virtualIP>:<port> using exactly the same ns-id as the URI authority and dfs.nameservices entry
2. Double-check the nameservice id spelling and case across all keys
3. If VIP failover is not actually deployed, use ObserverReadProxyProvider (or ConfiguredFailoverProxyProvider) instead

Example fix

<!-- before: provider set, VIP missing -->
<property>
  <name>dfs.client.failover.proxy.provider.ns1</name>
  <value>org.apache.hadoop.hdfs.server.namenode.ha.ObserverReadProxyProviderWithIPFailover</value>
</property>

<!-- after: add the virtual address for the nameservice -->
<property>
  <name>dfs.client.failover.ipfailover.virtual-address.ns1</name>
  <value>hdfs://10.0.0.5:8020</value>
</property>

String ns = uri.getHost();
String key = "dfs.client.failover.ipfailover.virtual-address." + ns;
if (conf.get(key) == null) {
  throw new IllegalArgumentException("Missing required config " + key);
}

When it happens

Trigger: Configuring dfs.client.failover.proxy.provider.<ns>=...ObserverReadProxyProviderWithIPFailover without the matching dfs.client.failover.ipfailover.virtual-address.<ns> entry, or with a nameservice id that differs (case/spelling) from the URI authority.

Common situations: Adopting Observer NameNode reads with VIP failover and forgetting the VIP key; config templates where the nameservice id casing differs between keys.

Related errors

• Can not create a Path from a null string
• Can not create a Path from an empty string
• no SharedFileDescriptorFactory paths were configured.
• Failed to create ${basePath}[source=${source}, allow-append=
• Error connecting to file system: ${basePath} [${ex}]

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