{"record":{"id":"d57a2fcd20aad7f5","repo":"apache/hadoop","slug":"hflush-not-supported-by-out","errorCode":null,"errorMessage":"hflush not supported by {out}","messagePattern":"hflush 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":125,"sourceCode":"\n  /**\n   * If the inner stream is Syncable, flush the buffer and then\n   * invoke the inner stream's hflush() 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 hflush() throws IOException {\n    if (out instanceof Syncable) {\n      flush();\n      ((Syncable) out).hflush();\n    } else {\n      if (!downgradeSyncable) {\n        throw new UnsupportedOperationException(\"hflush not supported by \"\n            + out);\n      } else {\n        flush();\n      }\n    }\n  }\n\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","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/fs/statistics/BufferedIOStatisticsOutputStream.java#L107-L143","documentation":"BufferedIOStatisticsOutputStream wraps an inner OutputStream to add buffering and IOStatistics collection. Its hflush() only works when the inner stream implements org.apache.hadoop.fs.Syncable: the buffer is flushed and the call forwarded. With a non-Syncable inner stream and downgradeSyncable=false (a constructor flag) it throws UnsupportedOperationException('hflush not supported by <out>').","triggerScenarios":"Constructing the wrapper around a stream that does not implement Syncable (compression codec streams, CipherOutputStream, plain in-memory streams, some test mocks) with downgradeSyncable=false, then calling hflush().","commonSituations":"Adding statistics instrumentation on top of encryption or compression layers; unit tests wrapping mock streams; pipelines where the bottom stream is not an FSDataOutputStream.","solutions":["Construct with downgradeSyncable=true when the durability guarantee is not required — the call degrades to flush(), matching FSDataOutputStream behavior","Make the inner stream implement Syncable (e.g. wrap it in FSDataOutputStream)","Probe 'out instanceof Syncable' before calling hflush()"],"exampleFix":"// before\nBufferedIOStatisticsOutputStream out =\n    new BufferedIOStatisticsOutputStream(inner, false);\nout.hflush(); // UnsupportedOperationException when inner is not Syncable\n\n// after\nBufferedIOStatisticsOutputStream out =\n    new BufferedIOStatisticsOutputStream(inner, true);\nout.hflush(); // degrades to flush()","handlingStrategy":"type-guard","validationCode":"if (out instanceof Syncable) {\n  statsStream.hflush();\n} else {\n  statsStream.flush(); // or construct the wrapper with downgradeSyncable=true\n}","typeGuard":"static boolean supportsHflush(OutputStream out) {\n  return out instanceof org.apache.hadoop.fs.Syncable;\n}","tryCatchPattern":"If you cannot control construction, catch UnsupportedOperationException from hflush() and degrade to flush() — but prefer the downgradeSyncable=true constructor flag so the behavior is explicit rather than exception-driven.","preventionTips":["Construct with downgradeSyncable=true when durability is optional","Keep an FSDataOutputStream (which is Syncable) at the bottom of flush pipelines","Probe instanceof Syncable before adding statistics wrappers"],"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-22T20:17:22.307Z"}