pentaho/pentaho-kettle · error · KettleStepException

JsonOutput.Error.OpenNewFile

JsonOutput.Error.OpenNewFile

Error message

JsonOutput.Error.OpenNewFile

What it means

In JsonOutput.outPutRow, when the step is configured to write to a file and the accumulated JSON array is non-empty, it calls openNewFile(); if that returns false it throws JsonOutput.Error.OpenNewFile including the built filename. This means the step could not open/create the target file for writing.

Solutions

1. Check the output filename in the step dialog; make sure the parent directory exists and the process user has write permission.
2. Use fully qualified paths or ${Internal.Transformation.Filename.Directory} variables instead of relative paths.
3. Verify environment variables in the filename resolve correctly (log the result of buildFilename()).
4. Close any program locking the target file, or write to a unique filename (include date/time variables).
5. Run the transformation as a user with sufficient filesystem permissions on the server/agent.

Example fix

// before (filename relative to unknown CWD)
${USER_DIR}/output.json
// after
${Internal.Transformation.Filename.Directory}/output.json

// Pre-flight check in the job before the transformation
File outDir = new File("/data/output");
if (!outDir.canWrite()) throw new IllegalStateException("Output dir not writable: " + outDir);

try { transformation.execute(...); } catch (KettleStepException e) {
  if (e.getMessage().contains("JsonOutput.Error.OpenNewFile")) {
    // parse filename from message, check existence/permissions, alert operator
  }
  throw e;
}

When it happens

Trigger: data.writeToFile is true, data.ja is non-empty, and openNewFile() returns false — typically because the path is invalid, the directory doesn't exist, the file is locked by another process, or permissions deny writing.

Common situations: Output filename points to a non-existent or read-only directory; file already open in another program (e.g. Excel/editor lock on Windows); relative path resolved differently because the transformation runs from a different working directory or on a server; filename with environment variables not substituted.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

• JsonOutput.Error.Writing
• Exception reading line using NIO:
• GetSubFolders.Exception.NoAccessibleFiles
• GroupBy.Exception.UnableToCloseInputStream
• GroupBy.Exception.UnableToReadBackRowFromTemporaryFile

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

Appendix: source

Thrown at plugins/json/core/src/main/java/org/pentaho/di/trans/steps/jsonoutput/JsonOutput.java:244

    String value;
    if ( data.realBlocName == "" ) {
      value = data.ja.toJSONString();
    } else {
      data.jg.put( data.realBlocName, data.ja );
      value = data.jg.toJSONString();
    }


    if ( data.outputValue && data.outputRowMeta != null ) {
      Object[] outputRowData = RowDataUtil.addValueData( rowData, data.inputRowMetaSize, value );
      incrementLinesOutput();
      putRow( data.outputRowMeta, outputRowData );
    }

    if ( data.writeToFile && !data.ja.isEmpty() ) {
      // Open a file
      if ( !openNewFile() ) {
        throw new KettleStepException( BaseMessages.getString(
          PKG, "JsonOutput.Error.OpenNewFile", buildFilename() ) );
      }
      // Write data to file
      try {
        data.writer.write( value );
      } catch ( Exception e ) {
        throw new KettleStepException( BaseMessages.getString( PKG, "JsonOutput.Error.Writing" ), e );
      }
      // Close file
      closeFile();
    }
    // Data are safe
    data.rowsAreSafe = true;
    data.ja = new JSONArray();
  }

  public boolean init( StepMetaInterface smi, StepDataInterface sdi ) {
    meta = (JsonOutputMeta) smi;

View on GitHub (pinned to f3058517a1)