apache/hadoop · error · FileSystemAccessException

H08

H08

Error message

{0}

What it means

FileSystemAccessService.createFileSystemInternal() creates a FileSystem as the end user via ugi.doAs(createFileSystem(conf)). IOExceptions and FileSystemAccessExceptions are rethrown unchanged; any other exception (RuntimeException/IllegalArgumentException from the Hadoop client, e.g. 'No FileSystem for scheme' or bad fs.defaultFS) is wrapped as error H08, whose message template '{0}' is just the original exception's message.

Source

Thrown at hadoop-hdfs-project/hadoop-hdfs-httpfs/src/main/java/org/apache/hadoop/lib/service/hadoop/FileSystemAccessService.java:398

    }
    try {
      validateNamenode(
          new URI(conf.getTrimmed(
              CommonConfigurationKeysPublic.FS_DEFAULT_NAME_KEY)).
                  getAuthority());
      UserGroupInformation ugi = getUGI(user);
      return ugi.doAs(new PrivilegedExceptionAction<FileSystem>() {
        @Override
        public FileSystem run() throws Exception {
          return createFileSystem(conf);
        }
      });
    } catch (IOException ex) {
      throw ex;
    } catch (FileSystemAccessException ex) {
      throw ex;
    } catch (Exception ex) {
      throw new FileSystemAccessException(FileSystemAccessException.ERROR.H08, ex.getMessage(), ex);
    }
  }

  @Override
  public FileSystem createFileSystem(String user, final Configuration conf) throws IOException,
    FileSystemAccessException {
    unmanagedFileSystems.incrementAndGet();
    return createFileSystemInternal(user, conf);
  }

  @Override
  public void releaseFileSystem(FileSystem fs) throws IOException {
    unmanagedFileSystems.decrementAndGet();
    closeFileSystem(fs);
  }

  @Override
  public Configuration getFileSystemConfiguration() {

View on GitHub (pinned to 2add963021)

Solutions

  1. Read the message - it is the original exception's message and names the real problem (scheme, class, property)
  2. Verify fs.defaultFS in the hadoop conf dir used by httpfs and that the scheme's implementation jar is on the httpfs classpath
  3. For custom filesystems, add the implementation jar to the httpfs webapp and ensure the fs.<scheme>.impl property is set
  4. Retry after fixing configuration; restart httpfs if classpath jars were changed

Example fix

# before: no implementation for scheme -> H08 'No FileSystem for scheme: myfs'
#   fs.defaultFS = myfs://nn1:8020

# after: ship the implementation jar to httpfs and register it in core-site.xml
<property><name>fs.myfs.impl</name><value>com.myco.MyFileSystem</value></property>
Defensive patterns

Strategy: validation

Validate before calling

import org.apache.hadoop.fs.FileSystem;

// Fail fast on a scheme httpfs cannot instantiate
java.net.URI u = java.net.URI.create(conf.get("fs.defaultFS"));
if (u.getScheme() != null) {
  java.util.Set<String> schemes = new java.util.HashSet<>(
      java.util.Arrays.asList(FileSystem.getDefaultUri(conf).getScheme()));
  Class<? extends FileSystem> impl = conf.getClass("fs." + u.getScheme() + ".impl", null, FileSystem.class);
  if (impl == null && !"hdfs".equals(u.getScheme()) && !"file".equals(u.getScheme())) {
    throw new IllegalStateException("no fs implementation for scheme " + u.getScheme());
  }
}

Try / catch

try {
  FileSystem fs = fsAccess.createFileSystem(user, conf);
} catch (FileSystemAccessException ex) {
  if (ex.getError() == FileSystemAccessException.ERROR.H08) {
    Throwable cause = ex.getCause(); // original RuntimeException, message preserved
    log.error("filesystem creation failed: {}", cause, ex);
  }
  throw ex;
}

Prevention

When it happens

Trigger: Calling FileSystemAccess.createFileSystem/createFileSystemInternal when createFileSystem(conf) throws a non-IOException: IllegalArgumentException for an unknown or unconfigured filesystem scheme, RuntimeException from DFSClient/static config misuse, or a ClassCastException from a misconfigured fs implementation class.

Common situations: fs.defaultFS scheme has no FileSystem implementation on the httpfs classpath (missing jar); core-site.xml io.file.buffer/fs impl misconfiguration; a custom filesystem implementation class not on the webapp classpath; version mismatch producing runtime errors during client init.

Related errors

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