What causes "AvroInput.Error.SchemaError" in pentaho/pentaho-kettle?

Verify the schema file path resolves correctly (resolve any ${variables} and check the file exists).

pentaho/pentaho-kettle · error · KettleException

AvroInput.Error.SchemaError

Error message

AvroInput.Error.SchemaError

What it means

The step loads the user-supplied Avro schema by parsing the file via KettleVFS; when opening/parsing fails with a FileSystemException, it is wrapped in a KettleException with the generic 'schema error' message. This indicates the schema file could not be accessed through the VFS layer.

Solutions

Verify the schema file path resolves correctly (resolve any ${variables} and check the file exists).
Check VFS connection settings/credentials for remote schemes (SFTP, HTTP, etc.).
Confirm read permissions on the schema file and its containing directory.
Test the exact resolved path with the same runtime user/agent running the transformation.

Example fix

// before
String schemaFile = "${AVRO_SCHEMA_DIR}/user.avsc"; // AVRO_SCHEMA_DIR unset
// after: set variable at runtime
transMeta.setVariable("AVRO_SCHEMA_DIR", "/opt/schemas");

Defensive patterns

Strategy: validation

Validate before calling

FileObject fo = KettleVFS.getFileObject(resolvedPath, space);
if (!fo.exists() || !fo.isReadable()) {
  throw new IllegalArgumentException("schema file missing or unreadable: " + resolvedPath);
}

Try / catch

try {
  rows = reader.avroObjectToKettle(row, space);
} catch (KettleException e) {
  if (e.getCause() instanceof FileSystemException) { alertBadSchemaPath(e.getCause()); stop(); } else throw e;
}

Prevention

Resolve and test all variables in the schema path at startup.
Check file existence and permissions before the transformation runs.
Use absolute paths or verified VFS connections for schema files.

When it happens

Trigger: Schema file path points to a non-existent/unreadable location, wrong VFS scheme/URL, or the file cannot be opened as an InputStream — thrown as FileSystemException before parsing even begins.

Common situations: Typos or stale variables in the schema filename field; missing env variables in paths like ${Internal...}/schema.avsc; no permission on the remote share; using http/ftp schemes without proper setup; file moved after configuration.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at plugins/avro-format/core/src/main/java/org/pentaho/di/trans/steps/avro/input/AvroNestedReader.java:1738

   * Load a schema from a file
   *
   * @param schemaFile the file to load from
   * @return the schema
   * @throws KettleException if a problem occurs
   */
  protected static Schema loadSchema( Bowl bowl, String schemaFile ) throws KettleException {

    Schema s = null;
    Schema.Parser p = new Schema.Parser();

    FileObject fileO = KettleVFS.getInstance( bowl ).getFileObject( schemaFile );
    try {
      InputStream in = KettleVFS.getInputStream( fileO );
      s = p.parse( in );

      in.close();
    } catch ( FileSystemException e ) {
      throw new KettleException( BaseMessages.getString( PKG, "AvroInput.Error.SchemaError" ), e );
    } catch ( IOException e ) {
      throw new KettleException( BaseMessages.getString( PKG, "AvroInput.Error.SchemaError" ), e );
    }

    return s;
  }

  /**
   * Load a schema from a Avro container file
   *
   * @param containerFilename the name of the Avro container file
   * @return the schema
   * @throws KettleException if a problem occurs
   */
  protected static Schema loadSchemaFromContainer( Bowl bowl, String containerFilename ) throws KettleException {
    Schema s = null;

    FileObject fileO = KettleVFS.getInstance( bowl ).getFileObject( containerFilename );

View on GitHub (pinned to f3058517a1)