\n * In some FileSystem implementations such as HDFS metadata\n * synchronization is essential to guarantee consistency of read requests\n * particularly in HA setting.\n * @throws IOException If an I/O error occurred.\n * @throws UnsupportedOperationException if the operation is unsupported.\n */\n public void msync() throws IOException, UnsupportedOperationException {\n throw new UnsupportedOperationException(getClass().getCanonicalName() +\n \" does not support method msync\");\n }\n\n /**\n * Checks if the user can access a path. The mode specifies which access\n * checks to perform. If the requested permissions are granted, then the\n * method returns normally. If access is denied, then the method throws an\n * {@link AccessControlException}.\n *
\n * The default implementation calls {@link #getFileStatus(Path)}\n * and checks the returned permissions against the requested permissions.\n *\n * Note that the {@link #getFileStatus(Path)} call will be subject to\n * authorization checks.\n * Typically, this requires search (execute) permissions on each directory in\n * the path's prefix, but this is implementation-defined. Any file system\n * that provides a richer authorization model (such as ACLs) may override the\n * default implementation so that it checks against that model instead.","sourceCodeStart":2790,"sourceCodeEnd":2826,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/FileSystem.java#L2790-L2826","documentation":"FileSystem.mync() synchronizes the client's metadata state so subsequent reads observe the latest namespace/block state — needed for consistent reads in HDFS HA (HDFS-13786). The base FileSystem throws UnsupportedOperationException; only HDFS clients (DistributedFileSystem, Hdfs) and pass-through wrappers (FilterFileSystem delegates; HarFileSystem no-ops) implement it. Local filesystem and object-store connectors reject the call entirely.","triggerScenarios":"Calling fs.msync() on LocalFileSystem (RawLocalFileSystem does not override it), S3A, ABFS, GCS, or a custom FileSystem that did not override the method; calling FileContext.msync() over such a store (AbstractFileSystem.msync has the same throwing default).","commonSituations":"Read-your-writes polling loops written for an HDFS HA cluster are run unchanged in local unit tests or against object stores; shared library code calls msync() unconditionally after open()/getFileStatus() to force consistency.","solutions":["Guard with fs instanceof DistributedFileSystem before calling msync()","Catch UnsupportedOperationException and continue: on stores without msync, reads are either already consistent or the call is meaningless — do not retry","If you own the FileSystem implementation, override msync() as a no-op when the store is already consistent (the HarFileSystem pattern)"],"exampleFix":"// before\nfs.msync(); // throws on LocalFileSystem/S3A/...\nPath p = new Path(\"/flag\");\n\n// after\nif (fs instanceof DistributedFileSystem) {\n fs.msync(); // only meaningful for HDFS HA consistency\n}\nPath p = new Path(\"/flag\");","handlingStrategy":"try-catch","validationCode":"if (fs instanceof DistributedFileSystem) {\n fs.msync(); // only HDFS implements metadata sync\n}","typeGuard":"static boolean supportsMsync(FileSystem fs) {\n return fs instanceof DistributedFileSystem;\n}","tryCatchPattern":"try {\n fs.msync();\n} catch (UnsupportedOperationException e) {\n // store is already consistent or has no msync concept: continue\n}","preventionTips":["Confine msync() calls to HDFS read-after-write consistency paths","In shared libraries, make msync best-effort: guard with instanceof or swallow UOE","When implementing a custom FileSystem on an eventually-consistent store, override msync() with real logic or a documented no-op"],"tags":["hadoop","filesystem","hdfs","msync","unsupportedoperationexception","metadata-consistency","ha"],"backgroundTag":"filesystem-unsupported-operation","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}