apache/hadoop · error · UnsupportedOperationException

{getClass().getCanonicalName()} does not support method msyn

Error message

{getClass().getCanonicalName()} does not support method msync

What it means

msync() forces the client to refresh cached namespace metadata with the NameNode, needed for read-your-writes consistency after asynchronous HDFS operations. Only the HDFS AbstractFileSystem implements it; the base default throws UnsupportedOperationException naming the concrete class, so fc.msync() (FileContext delegates to defaultFS.msync()) fails on every non-HDFS filesystem.

Source

Thrown at hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/AbstractFileSystem.java:1029

   * @throws UnresolvedLinkException unresolved link exception.
   * @throws IOException raised on errors performing I/O.
   * @return File Status
   */
  public abstract FileStatus getFileStatus(final Path f)
      throws AccessControlException, FileNotFoundException,
      UnresolvedLinkException, IOException;

  /**
   * Synchronize client metadata state.
   * <p>
   * In some FileSystem implementations such as HDFS metadata
   * synchronization is essential to guarantee consistency of read requests
   * particularly in HA setting.
   * @throws IOException raised on errors performing I/O.
   * @throws UnsupportedOperationException Unsupported Operation Exception.
   */
  public void msync() throws IOException, UnsupportedOperationException {
    throw new UnsupportedOperationException(getClass().getCanonicalName() +
        " does not support method msync");
  }

  /**
   * The specification of this method matches that of
   * {@link FileContext#access(Path, FsAction)}
   * except that an UnresolvedLinkException may be thrown if a symlink is
   * encountered in the path.
   *
   * @param path the path.
   * @param mode fsaction mode.
   * @throws AccessControlException access control exception.
   * @throws FileNotFoundException file not found exception.
   * @throws UnresolvedLinkException unresolved link exception.
   * @throws IOException raised on errors performing I/O.
   */
  @InterfaceAudience.LimitedPrivate({"HDFS", "Hive"})
  public void access(Path path, FsAction mode) throws AccessControlException,

View on GitHub (pinned to 2add963021)

Solutions

1. Gate the call by scheme: only invoke msync when the path/filesystem scheme is hdfs (msync is a no-op need everywhere else)
2. Catch UnsupportedOperationException and treat msync as best-effort metadata hygiene
3. Only call msync when you actually issued asynchronous operations whose metadata you must observe

Example fix

// before
fc.msync(); // on file:// -> UnsupportedOperationException

// after
if ("hdfs".equalsIgnoreCase(path.toUri().getScheme())) {
  fc.msync();
}

if ("hdfs".equalsIgnoreCase(path.toUri().getScheme())) {
  fc.msync();
}

try { fc.msync(); } catch (UnsupportedOperationException e) { /* non-HDFS backend: metadata caching not applicable, continue */ }

When it happens

Trigger: fc.msync() on file://, viewfs:, s3a://, adl://, etc.; library code that unconditionally calls msync after asynchronous Callables (Future* create/append) regardless of the scheme; unit tests of HDFS logic running against LocalFs.

Common situations: Client code parameterized over fs.defaultFS that works on HDFS but breaks in local tests; frameworks adopting the async-call + msync pattern; jobs migrated from HDFS to object stores.

Related errors

• File system does not support symlinks
• {getClass().getCanonicalName()} does not support listCorrupt
• {getClass().getSimpleName()} doesn't support modifyAclEntrie
• {getClass().getSimpleName()} doesn't support removeAclEntrie
• {getClass().getSimpleName()} doesn't support removeDefaultAc

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