pentaho/pentaho-kettle · error · KettleException

AutoDoc.Exception.UnableToRenderReport

Error message

AutoDoc.Exception.UnableToRenderReport

What it means

AutoDoc.processRow throws KettleException wrapping 'AutoDoc.Exception.UnableToRenderReport' when report generation for the Auto Documentation Output step fails. After collecting result files, any exception while rendering the report (target file creation, report engine errors) is wrapped. It means the documentation output file could not be produced.

Solutions

1. Check the output directory exists and the process can write to it.
2. Verify the target file extension matches a supported report output type (HTML, XLS, PDF) and required renderer libs are on the classpath.
3. Free disk space if the volume is full.
4. Test with a simple filename (no special characters) in a temp directory.

Example fix

// before: output file field resolves to /readonly/report.pdf
// after: point filename field to a writable path like /tmp/report.pdf or grant write access

File outDir = new File(environmentSubstitute(meta.getFilenameField())).getParentFile();
if (outDir == null || !outDir.canWrite()) {
  throw new IllegalStateException("Output directory missing or not writable: " + outDir);
}

try {
  processRowInternal();
} catch (KettleException e) {
  if (e.getMessage().contains("UnableToRenderReport")) {
    logError("Report render failed: " + e.getMessage(), e);
    setErrors(1);
  }
}

When it happens

Trigger: At runtime in processRow when the report renderer throws: invalid target filename/type (e.g. unsupported extension like .pdf without a renderer), unwritable output directory, or disk full.

Common situations: Output folder lacking write permission; output type (PDF/HTML/XLS) whose renderer library is missing; invalid filename from the filename field.

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

• All input files need to have the same number of fields. File
• AutoDoc.Exception.FilenameFieldNotFound
• AutoDoc.Exception.FileTypeFieldNotFound
• AutoDoc.Exception.UnableToDetermineLocation
• AutoDoc.Exception.UnknownFileTypeValue

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

Appendix: source

Thrown at plugins/core/impl/src/main/java/org/pentaho/di/trans/steps/autodoc/AutoDoc.java:124

        kettleReportBuilder.createReport();
        kettleReportBuilder.render();

        Object[] outputRowData = RowDataUtil.allocateRowData( data.outputRowMeta.size() );
        int outputIndex = 0;
        outputRowData[outputIndex++] = targetFilename;

        // Pass along the data to the next steps...
        //
        putRow( data.outputRowMeta, outputRowData );

        // Add the target file to the result file list
        //
        ResultFile resultFile =
          new ResultFile( ResultFile.FILE_TYPE_GENERAL, targetFile, getTransMeta().getName(), toString() );
        resultFile.setComment( "This file was generated by the 'Auto Documentation Output' step" );
        addResultFile( resultFile );
      } catch ( Exception e ) {
        throw new KettleException( BaseMessages.getString( PKG, "AutoDoc.Exception.UnableToRenderReport" ), e );
      }

      setOutputDone();
      return false;
    }

    if ( first ) {
      first = false;

      data.outputRowMeta = getInputRowMeta().clone();
      meta.getFields( getTransMeta().getBowl(), data.outputRowMeta, getStepname(), null, null, this, repository,
        metaStore );

      // Get the filename field index...
      //
      String filenameField = environmentSubstitute( meta.getFilenameField() );
      data.fileNameFieldIndex = getInputRowMeta().indexOfValue( filenameField );
      if ( data.fileNameFieldIndex < 0 ) {

View on GitHub (pinned to f3058517a1)