pentaho/pentaho-kettle · error · KettleXMLException

Unable to save to XML file '" + filename + "'

Error message

Unable to save to XML file '" + filename + "'

What it means

TransMeta.saveToKtr(filename) (save-to-XML) opens a FileOutputStream, writes the XML header and getXML() body, and wraps any failure (file creation, encoding, serialization) in KettleXMLException 'Unable to save to XML file <filename>'. It indicates the transformation could not be written to disk.

Solutions

1. Verify the target directory exists and is writable; create it before saving (new File(dir).mkdirs()).
2. Check free disk space and user write permissions on the path.
3. Use an absolute path and confirm the filename has no illegal characters for the OS.
4. Catch KettleXMLException and inspect the cause for the exact filesystem error.

Example fix

// before
transMeta.saveToKtr("transforms/mytrans.ktr"); // dir missing
// after
new File("transforms").mkdirs();
transMeta.saveToKtr("/abs/path/transforms/mytrans.ktr");

File target = new File(filename);
if (!target.getParentFile().exists()) target.getParentFile().mkdirs();
if (!target.getParentFile().canWrite()) throw new IllegalStateException("Directory not writable: " + target.getParent());

try {
  transMeta.saveToKtr(filename);
} catch (KettleXMLException e) {
  log.error("Save to XML failed for " + filename, e.getCause());
}

When it happens

Trigger: Calling TransMeta.saveToKtr(filename) (or File > Save As in Spoon) when new FileOutputStream(filename) or the write of getXML() bytes throws — e.g. directory missing, no write permission, disk full, or XML serialization failure.

Common situations: Saving a KTR to a non-existent directory; read-only filesystem or no permission; path too long on Windows; disk quota exceeded; Const.XML_ENCODING mismatch on exotic content.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• ChangeFileEncoding.Error.CreatingFile
• Error writing line :
• Error writing XML row :
• ex.getMessage()
• Exporting jobs: Couldn't create file

AI-assisted analysis of pentaho/pentaho-kettle@f3058517a1 (2026-09-13). Data as JSON: /api/errors/ebf17b8a524103ba. Report an issue: GitHub.

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/trans/TransMeta.java:6598

    this.transformationType = transformationType;
  }

  /**
   * Utility method to write the XML of this transformation to a file, mostly for testing purposes.
   *
   * @param filename
   *          The filename to save to
   * @throws KettleXMLException
   *           in case something goes wrong.
   */
  public void writeXML( String filename ) throws KettleXMLException {
    FileOutputStream fos = null;
    try {
      fos = new FileOutputStream( filename );
      fos.write( XMLHandler.getXMLHeader().getBytes( Const.XML_ENCODING ) );
      fos.write( getXML().getBytes( Const.XML_ENCODING ) );
    } catch ( Exception e ) {
      throw new KettleXMLException( "Unable to save to XML file '" + filename + "'", e );
    } finally {
      if ( fos != null ) {
        try {
          fos.close();
        } catch ( IOException e ) {
          throw new KettleXMLException( "Unable to close file '" + filename + "'", e );
        }
      }
    }
  }

  /**
   * Checks whether the transformation has repository references.
   *
   * @return true if the transformation has repository references, false otherwise
   */
  public boolean hasRepositoryReferences() {
    for ( StepMeta stepMeta : steps ) {

View on GitHub (pinned to f3058517a1)