pentaho/pentaho-kettle · error · KettleFileException

Unable to write value data to output stream

Error message

Unable to write value data to output stream

What it means

This KettleFileException is thrown by Value.writeObj's data-writing path when an IOException occurs while writing the value's payload to a DataOutputStream. It wraps low-level stream failures (disk full, closed/broken stream, network failure) into Kettle's checked exception type so callers of value serialization get a single error type.

Solutions

  1. Check disk space and write permissions on the target before starting the write.
  2. Ensure the consumer keeps the socket/pipe open until the producer finishes (fix premature close on the reader side).
  3. Retry the whole write operation on transient network errors, writing to a temp file and renaming on success.
  4. Wrap output in BufferedOutputStream and close in try-with-resources to avoid resource leaks causing later failures.
  5. Catch KettleFileException and inspect getCause() (IOException) for the concrete OS-level reason.

Example fix

// before
value.writeObj( dos ); // KettleFileException if stream broken
// after
try {
  value.writeObj( dos );
  dos.flush();
} catch ( KettleFileException e ) {
  throw new IOException( "Failed to persist value data: " + e.getCause().getMessage(), e );
}
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-flight checks before writing
File target = new File( path );
if ( target.getUsableSpace() < requiredBytes ) throw new IOException( "Insufficient disk space" );
if ( !target.getParentFile().canWrite() ) throw new IOException( "No write permission: " + path );

Try / catch

try {
  value.writeObj( dos );
  dos.flush();
} catch ( KettleFileException e ) {
  if ( e.getCause() instanceof IOException && isTransient( (IOException) e.getCause() ) ) {
    retryWrite();
  } else {
    throw e;
  }
}

Prevention

When it happens

Trigger: Calling the Value serialization/write API (writeObj / row serialization to file or socket) when the underlying OutputStream is closed, broken (broken pipe), out of disk space, or a network socket dies mid-write.

Common situations: Writing kettle data files to a full disk; a consumer closed the pipe/socket while the producer still writes; network interruptions during streaming output; writing to a file on a read-only or removed mount.

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

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

Appendix: source

Thrown at core/src/main/java/org/pentaho/di/compatibility/Value.java:1699

            if ( getDate() != null ) {
              dos.writeLong( getDate().getTime() );
            }
            break;
          case VALUE_TYPE_NUMBER:
            dos.writeDouble( getNumber() );
            break;
          case VALUE_TYPE_BOOLEAN:
            dos.writeBoolean( getBoolean() );
            break;
          case VALUE_TYPE_INTEGER:
            dos.writeLong( getInteger() );
            break;
          default:
            break; // nothing
        }
      }
    } catch ( IOException e ) {
      throw new KettleFileException( "Unable to write value data to output stream", e );
    }

    return true;
  }

  /**
   * Read the data of a Value from a DataInputStream, the meta-data of the value has to be set before calling this
   * method!
   *
   * @param dis
   *          the DataInputStream to read from
   * @throws KettleFileException
   *           when the value couldn't be read from the DataInputStream
   */
  public Value( Value metaData, DataInputStream dis ) throws KettleFileException {
    setValue( metaData );
    setName( metaData.getName() );

View on GitHub (pinned to f3058517a1)