{"record":{"id":"46842663a5c6dd86","repo":"apache/hadoop","slug":"image-compression-codec-not-supported-codecclass","errorCode":null,"errorMessage":"Image compression codec not supported: {codecClassName}","messagePattern":"Image compression codec not supported: (.+?)","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/ImageLoaderCurrent.java","lineNumber":208,"sourceCode":"        v.visit(ImageElement.SNAPSHOT_COUNTER, in.readInt());\n        int numSnapshots = in.readInt();\n        v.visit(ImageElement.NUM_SNAPSHOTS_TOTAL, numSnapshots);\n        for (int i = 0; i < numSnapshots; i++) {\n          processSnapshot(in, v);\n        }\n      }\n      \n      if (NameNodeLayoutVersion.supports(Feature.FSIMAGE_COMPRESSION, imageVersion)) {\n        boolean isCompressed = in.readBoolean();\n        v.visit(ImageElement.IS_COMPRESSED, String.valueOf(isCompressed));\n        if (isCompressed) {\n          String codecClassName = Text.readString(in);\n          v.visit(ImageElement.COMPRESS_CODEC, codecClassName);\n          CompressionCodecFactory codecFac = new CompressionCodecFactory(\n              new Configuration());\n          CompressionCodec codec = codecFac.getCodecByClassName(codecClassName);\n          if (codec == null) {\n            throw new IOException(\"Image compression codec not supported: \"\n                + codecClassName);\n          }\n          in = new DataInputStream(codec.createInputStream(in));\n        }\n      }\n      processINodes(in, v, numInodes, skipBlocks, supportSnapshot);\n      subtreeMap.clear();\n      dirNodeMap.clear();\n\n      processINodesUC(in, v, skipBlocks);\n\n      if (NameNodeLayoutVersion.supports(Feature.DELEGATION_TOKEN, imageVersion)) {\n        processDelegationTokens(in, v);\n      }\n      \n      if (NameNodeLayoutVersion.supports(Feature.CACHING, imageVersion)) {\n        processCacheManagerState(in, v);\n      }","sourceCodeStart":190,"sourceCodeEnd":226,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/tools/offlineImageViewer/ImageLoaderCurrent.java#L190-L226","documentation":"When a legacy fsimage records FSIMAGE_COMPRESSION=true, ImageLoaderCurrent reads the codec class name stored in the image and resolves it via CompressionCodecFactory.getCodecByClassName, which only sees codecs discoverable on the tool's classpath. A null return means no codec with that class name is registered, so the (compressed) remainder of the image cannot be decompressed and loading stops. This is a classpath/dependency problem, not image corruption.","triggerScenarios":"`hdfs oiv_legacy` on an fsimage checkpointed with dfs.image.compression.codec set to a codec absent from the tool's classpath - classically LZO (com.hadoop.compression.lzo.LzopCodec), a site-custom codec, or Bzip2 with missing native libraries; also running oiv with a trimmed classpath (custom `hadoop jar ... -libjars`) that omits the codec jar.","commonSituations":"Clusters compressing checkpoints with LZO to save space; processing images on a gateway host that lacks hadoop-lzo; version skew where the codec jar moved or was renamed between Hadoop releases.","solutions":["Put the codec jar on the tool classpath: HADOOP_CLASSPATH=/path/to/hadoop-lzo.jar hdfs oiv_legacy -p Indented -i <fsimage> -o out.txt","Run oiv on a host with the full cluster classpath (same $HADOOP_HOME layout as the NameNode)","If the codec is unsupported site-wide, roll a fresh checkpoint with dfs.image.compress=false (or the default DefaultCodec/gzip) and process that image","Verify discovery beforehand: hadoop classpath | grep -i lzo"],"exampleFix":"# before\nhdfs oiv_legacy -p Indented -i fsimage_lzo -o out.txt\n# IOException: Image compression codec not supported: com.hadoop.compression.lzo.LzopCodec\n\n# after\nHADOOP_CLASSPATH=/opt/hadoop/lib/hadoop-lzo-0.4.20.jar \\\n  hdfs oiv_legacy -p Indented -i fsimage_lzo -o out.txt","handlingStrategy":"validation","validationCode":"// Confirm the image's codec is resolvable on THIS classpath before oiv runs\nCompressionCodecFactory factory =\n    new CompressionCodecFactory(new Configuration());\nString codecClass = \"com.hadoop.compression.lzo.LzopCodec\"; // your dfs.image.compression.codec\nif (factory.getCodecByClassName(codecClass) == null) {\n  throw new IllegalStateException(\n      \"Codec \" + codecClass + \" not on classpath - add its jar via HADOOP_CLASSPATH\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  ImageLoader loader = ImageLoader.loadImage(version);\n  loader.loadImage(in, visitor, skipBlocks);\n} catch (IOException e) {\n  if (e.getMessage().startsWith(\"Image compression codec not supported\")) {\n    // recoverable by classpath fix, not by retrying the same command\n    throw new IllegalStateException(\"Add the codec jar to HADOOP_CLASSPATH and rerun\", e);\n  }\n  throw e;\n}","preventionTips":["Keep every checkpoint codec jar present on admin/gateway hosts, not just DataNodes","Document dfs.image.compression.codec next to the oiv commands in runbooks","Prefer built-in codecs (DefaultCodec/gzip) for fsimages that must be portable"],"tags":["hdfs","fsimage","compression-codec","classpath","offline-image-viewer"],"backgroundTag":"unsupported-compression-codec","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}