apache/hadoop · critical · ServerException

S04

S04

Error message

Service [{0}] does not implement declared interface [{1}]

What it means

Server.loadServices() instantiates each class listed in the services config (httpfs.services) and verifies that the instance really implements the interface its own getInterface() declares; a mismatch throws ServerException S04('Service [<class>] does not implement declared interface [<iface>]'). Any other instantiation failure is instead S07 — S04 specifically means the object was created but its self-declared contract is inconsistent.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/server/Server.java:523

  }

  /**
   * Loads the specified services.
   *
   * @param classes services classes to load.
   * @param list list of loaded service in order of appearance in the
   * configuration.
   *
   * @throws ServerException thrown if a service class could not be loaded.
   */
  private void loadServices(Class[] classes, List<Service> list) throws ServerException {
    for (Class klass : classes) {
      try {
        Service service = (Service) klass.newInstance();
        log.debug("Loading service [{}] implementation [{}]", service.getInterface(),
                  service.getClass());
        if (!service.getInterface().isInstance(service)) {
          throw new ServerException(ServerException.ERROR.S04, klass, service.getInterface().getName());
        }
        list.add(service);
      } catch (ServerException ex) {
        throw ex;
      } catch (Exception ex) {
        throw new ServerException(ServerException.ERROR.S07, klass, ex.getMessage(), ex);
      }
    }
  }

  /**
   * Loads services defined in <code>services</code> and
   * <code>services.ext</code> and de-dups them.
   *
   * @return List of final services to initialize.
   *
   * @throws ServerException throw if the services could not be loaded.
   */

View on GitHub (pinned to 2add963021)

Solutions

1. Inspect httpfs.services in httpfs-site.xml, find the class named in {0}, and fix its getInterface() to return an interface the class actually implements (or make the class implement the declared interface).
2. Remove stale duplicate versions of the service jar from the classpath (only one compatible version should remain).
3. If the service is third-party, check for a fixed release matching your Hadoop/HttpFS version.
4. Temporarily drop the broken entry from httpfs.services to bring the server up while you fix it.

Example fix

// before
public class MyService implements Service {
  public Class<?> getInterface() { return OtherService.class; }  // not implemented -> S04
}

// after
public class MyService implements MyServiceInterface, Service {
  public Class<?> getInterface() { return MyServiceInterface.class; }
}

// deploy-time smoke test: every configured service must satisfy its contract
String[] classes = conf.getStrings("httpfs.services");
for (String cn : classes) {
  Service s = (Service) Class.forName(cn).getDeclaredConstructor().newInstance();
  if (!s.getInterface().isInstance(s)) {
    throw new IllegalStateException(cn + " does not implement " + s.getInterface().getName());
  }
}

static boolean serviceContractOk(Class<? extends Service> klass) throws Exception {
  Service s = klass.getDeclaredConstructor().newInstance();
  return s.getInterface().isInstance(s);
}

When it happens

Trigger: A custom Service class whose getInterface() returns an interface it does not implement (copy-paste template bug); refactoring a service so it no longer implements its original interface while getInterface() was not updated; mixing JAR versions where a service and its interface drift; shading/relocation breaking the interface identity check.

Common situations: First deploy of an in-house HttpFS service; upgrading a custom service jar without updating its interface wiring; duplicate/old service jars left on the classpath after an upgrade.

Related errors

• [{0}] must be an absolute path [{1}]
• S01
• S02
• S03
• S05

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