{"record":{"id":"0e5b61798e48cc4a","repo":"pentaho/pentaho-kettle","slug":"unable-to-serialize-image-to-png","errorCode":null,"errorMessage":"Unable to serialize image to PNG","messagePattern":"Unable to serialize image to PNG","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/autodoc/AutoDoc.java","lineNumber":286,"sourceCode":"      if ( meta.isIncludingCreated() ) {\n        outputRow[outputIndex++] = KettleFileTableModel.getCreation( getTransMeta().getBowl(), location );\n      }\n\n      // modified\n      if ( meta.isIncludingModified() ) {\n        outputRow[outputIndex++] = KettleFileTableModel.getModification( getTransMeta().getBowl(), location );\n      }\n\n      // image\n      if ( meta.isIncludingImage() ) {\n        ByteArrayOutputStream outputStream = new ByteArrayOutputStream();\n        try {\n          BufferedImage image = KettleFileTableModel.getImage( getTransMeta().getBowl(), location );\n          ImageIO.write( image, \"png\", outputStream );\n\n          outputRow[outputIndex++] = outputStream.toByteArray();\n        } catch ( Exception e ) {\n          throw new KettleException( \"Unable to serialize image to PNG\", e );\n        } finally {\n          try {\n            outputStream.close();\n          } catch ( IOException e ) {\n            throw new KettleException( \"Unable to serialize image to PNG\", e );\n          }\n        }\n      }\n\n      if ( meta.isIncludingLoggingConfiguration() ) {\n        outputRow[outputIndex++] = KettleFileTableModel.getLogging( getTransMeta().getBowl(), location );\n      }\n\n      if ( meta.isIncludingLastExecutionResult() ) {\n        outputRow[outputIndex++] = KettleFileTableModel.getLogging( getTransMeta().getBowl(), location );\n      }\n\n      if ( meta.isIncludingImageAreaList() ) {","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/autodoc/AutoDoc.java#L268-L304","documentation":"AutoDoc.processRow throws KettleException 'Unable to serialize image to PNG' (hardcoded, no message key) when KettleFileTableModel.getImage returns a bad image or ImageIO.write fails, or when closing the ByteArrayOutputStream throws IOException. The step captures a diagram image for each subject into a PNG byte array for the output row.","triggerScenarios":"KettleFileTableModel.getImage returns null or throws (subject not renderable), ImageIO.write cannot encode the BufferedImage to PNG, or outputStream.close() throws IOException in the finally block.","commonSituations":"Headless servers without AWT graphics support (no DISPLAY / java.awt.headless issues); corrupt or unavailable transformation/job metadata preventing diagram rendering; JVM missing PNG image writer.","solutions":["Run the JVM in headless mode (-Djava.awt.headless=true) on servers, or ensure a working DISPLAY/X server is available.","Check the referenced transformation/job renders correctly in Spoon; fix its metadata if the diagram generation fails.","Verify the JDK includes the standard PNG ImageWriter (ImageIO.getWriterFormatNames()).","Update Kettle to a version where image rendering for the subject type is supported."],"exampleFix":"// before: java -jar kitchen.jar ...\n// after\njava -Djava.awt.headless=true -jar kitchen.jar ...","handlingStrategy":"try-catch","validationCode":"// Check PNG writer and headless support before running\nif (ImageIO.write(ImageIO.createImage(1, 1, BufferedImage.TYPE_INT_RGB).orElse(null), \"png\", new ByteArrayOutputStream()) == false &&\n    !ImageIO.getImageWritersByFormatName(\"png\").hasNext()) {\n  throw new IllegalStateException(\"No PNG image writer available in this JVM\");\n}","typeGuard":"public static boolean isRenderable(BufferedImage image) {\n  return image != null && image.getWidth() > 0 && image.getHeight() > 0;\n}","tryCatchPattern":"try {\n  BufferedImage image = KettleFileTableModel.getImage(bowl, location);\n  if (image == null) throw new IllegalStateException(\"No image for \" + location);\n  ImageIO.write(image, \"png\", outputStream);\n} catch (Exception e) {\n  logError(\"PNG serialization failed: \" + e.getMessage(), e);\n  setErrors(1);\n}","preventionTips":["Start the JVM with -Djava.awt.headless=true on servers.","Verify diagrams render in Spoon for all subjects being documented.","Confirm the JDK has standard ImageIO PNG support."],"tags":["kettle","image","awt","serialization","runtime"],"backgroundTag":"unsupported-operation","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}