{"record":{"id":"7d5f63a1a4789743","repo":"apache/hadoop","slug":"s04","errorCode":"S04","errorMessage":"Service [{0}] does not implement declared interface [{1}]","messagePattern":"Service \\[(.+?)\\] does not implement declared interface \\[(.+?)\\]","errorType":"error_code","errorClass":"ServerException","httpStatus":null,"severity":"critical","filePath":"hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/server/Server.java","lineNumber":523,"sourceCode":"  }\n\n  /**\n   * Loads the specified services.\n   *\n   * @param classes services classes to load.\n   * @param list list of loaded service in order of appearance in the\n   * configuration.\n   *\n   * @throws ServerException thrown if a service class could not be loaded.\n   */\n  private void loadServices(Class[] classes, List<Service> list) throws ServerException {\n    for (Class klass : classes) {\n      try {\n        Service service = (Service) klass.newInstance();\n        log.debug(\"Loading service [{}] implementation [{}]\", service.getInterface(),\n                  service.getClass());\n        if (!service.getInterface().isInstance(service)) {\n          throw new ServerException(ServerException.ERROR.S04, klass, service.getInterface().getName());\n        }\n        list.add(service);\n      } catch (ServerException ex) {\n        throw ex;\n      } catch (Exception ex) {\n        throw new ServerException(ServerException.ERROR.S07, klass, ex.getMessage(), ex);\n      }\n    }\n  }\n\n  /**\n   * Loads services defined in <code>services</code> and\n   * <code>services.ext</code> and de-dups them.\n   *\n   * @return List of final services to initialize.\n   *\n   * @throws ServerException throw if the services could not be loaded.\n   */","sourceCodeStart":505,"sourceCodeEnd":541,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/server/Server.java#L505-L541","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Remove stale duplicate versions of the service jar from the classpath (only one compatible version should remain).","If the service is third-party, check for a fixed release matching your Hadoop/HttpFS version.","Temporarily drop the broken entry from httpfs.services to bring the server up while you fix it."],"exampleFix":"// before\npublic class MyService implements Service {\n  public Class<?> getInterface() { return OtherService.class; }  // not implemented -> S04\n}\n\n// after\npublic class MyService implements MyServiceInterface, Service {\n  public Class<?> getInterface() { return MyServiceInterface.class; }\n}","handlingStrategy":"validation","validationCode":"// deploy-time smoke test: every configured service must satisfy its contract\nString[] classes = conf.getStrings(\"httpfs.services\");\nfor (String cn : classes) {\n  Service s = (Service) Class.forName(cn).getDeclaredConstructor().newInstance();\n  if (!s.getInterface().isInstance(s)) {\n    throw new IllegalStateException(cn + \" does not implement \" + s.getInterface().getName());\n  }\n}","typeGuard":"static boolean serviceContractOk(Class<? extends Service> klass) throws Exception {\n  Service s = klass.getDeclaredConstructor().newInstance();\n  return s.getInterface().isInstance(s);\n}","tryCatchPattern":null,"preventionTips":["Unit-test custom services with the same isInstance(getInterface()) check that Server applies.","Remove old service jars during upgrades to avoid version-drift instances.","Add the service smoke test to CI for anything registered in httpfs.services."],"tags":["httpfs","server-startup","service-loading","custom-service","class-identity"],"backgroundTag":"service-load-failure","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}