{"record":{"id":"e865fcc1bd489ff7","repo":"apache/hadoop","slug":"hsync-not-supported-by-out","errorCode":null,"errorMessage":"hsync not supported by {out}","messagePattern":"hsync not supported by (.+?)","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/statistics/BufferedIOStatisticsOutputStream.java","lineNumber":150,"sourceCode":"\n  /**\n   * If the inner stream is Syncable, flush the buffer and then\n   * invoke the inner stream's hsync() operation.\n   *\n   * Otherwise: throw an exception, unless the stream was constructed with\n   * {@link #downgradeSyncable} set to true, in which case the stream\n   * is just flushed.\n   * @throws IOException IO Problem\n   * @throws UnsupportedOperationException if the inner class is not syncable\n   */\n  @Override\n  public void hsync() throws IOException {\n    if (out instanceof Syncable) {\n      flush();\n      ((Syncable) out).hsync();\n    } else {\n      if (!downgradeSyncable) {\n        throw new UnsupportedOperationException(\"hsync not supported by \"\n            + out);\n      } else {\n        flush();\n      }\n    }\n  }\n}\n","sourceCodeStart":132,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/statistics/BufferedIOStatisticsOutputStream.java#L132-L158","documentation":"BufferedIOStatisticsOutputStream.hsync() mirrors hflush(): the inner stream must implement org.apache.hadoop.fs.Syncable for the sync to be forwarded after the buffer flush. If the inner stream is not Syncable and downgradeSyncable=false, UnsupportedOperationException('hsync not supported by <out>') is thrown.","triggerScenarios":"Constructing the wrapper over a non-Syncable stream (compression, crypto, in-memory, mock streams) with downgradeSyncable=false, then calling hsync() to force durability.","commonSituations":"Durability flushes ('hsync' for data + metadata) attempted on instrumented pipelines whose bottom layer is not Syncable; tests with mock inner streams.","solutions":["Construct with downgradeSyncable=true if a plain flush is acceptable","Ensure the inner stream implements Syncable (wrap it in FSDataOutputStream)","Check 'out instanceof Syncable' before calling hsync()"],"exampleFix":"// before\nBufferedIOStatisticsOutputStream out =\n    new BufferedIOStatisticsOutputStream(inner, false);\nout.hsync(); // UnsupportedOperationException when inner is not Syncable\n\n// after\nBufferedIOStatisticsOutputStream out =\n    new BufferedIOStatisticsOutputStream(inner, true);\nout.hsync(); // degrades to flush()","handlingStrategy":"type-guard","validationCode":"if (out instanceof Syncable) {\n  statsStream.hsync();\n} else {\n  statsStream.flush(); // or construct the wrapper with downgradeSyncable=true\n}","typeGuard":"static boolean supportsHsync(OutputStream out) {\n  return out instanceof org.apache.hadoop.fs.Syncable;\n}","tryCatchPattern":"Catch UnsupportedOperationException from hsync() and fall back to flush() only as a last resort; the constructor flag downgradeSyncable=true makes the downgrade explicit and non-throwing.","preventionTips":["Set downgradeSyncable=true unless you require the Syncable durability contract","Verify the innermost stream of a layered pipeline implements Syncable","Test hsync paths with realistic inner streams, not bare mocks"],"tags":["hadoop","io","output-stream","syncable","statistics","unsupported-operation"],"backgroundTag":"stream-not-syncable","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-23T01:17:44.959Z"}