What causes "Operation [{operation}] is unknown to the security handler." in pentaho/pentaho-kettle?

Upgrade the Kettle engine so KettleFileRepositorySecurityProvider handles the operation.

pentaho/pentaho-kettle · error · KettleException

Operation [ ] is unknown to the security handler.

Error message

Operation [{operation}] is unknown to the security handler.

What it means

validateAction's default branch throws when the given RepositoryOperation enum value is not handled by the file-repository security provider's switch. This usually means a newer operation was added to the RepositoryOperation enum that this security provider does not yet recognize, or an invalid operation is passed programmatically.

Solutions

Upgrade the Kettle engine so KettleFileRepositorySecurityProvider handles the operation.
Wrap the custom operation in a handled RepositoryOperation case or extend the security provider.
Log the actual operation value from the message to identify the unhandled enum constant.
Check for mixed kettle-engine jars on the classpath and align versions.

Example fix

// before
provider.validateAction(RepositoryOperation.MY_NEW_OPERATION); // unhandled
// after
if (isOperationSupported(provider, RepositoryOperation.MY_NEW_OPERATION)) {
  provider.validateAction(RepositoryOperation.MY_NEW_OPERATION);
}

Defensive patterns

Strategy: try-catch

Validate before calling

Set<RepositoryOperation> supported = Set.of(READ_TRANSFORMATION, ... /* handled ops */);
if (!supported.contains(operation)) {
  throw new IllegalArgumentException("Operation not supported by file repo security provider: " + operation);
}

Type guard

boolean isKnownOperation(RepositoryOperation op) {
  switch (op) {
    case DELETE_JOB: case MODIFY_DATABASE: case DELETE_DATABASE:
    case MODIFY_SLAVE_SERVER: case MODIFY_CLUSTER_SCHEMA: case MODIFY_PARTITION_SCHEMA:
    case DELETE_SLAVE_SERVER: case DELETE_CLUSTER_SCHEMA: case DELETE_PARTITION_SCHEMA:
      return true;
    default: return false;
  }
}

Try / catch

try {
  provider.validateAction(operation);
} catch (KettleException e) {
  if (e.getMessage() != null && e.getMessage().contains("is unknown to the security handler")) {
    // upgrade engine version or bypass for supported-only ops
  } else { throw e; }
}

Prevention

Align kettle-engine versions across classpath/plugins to avoid unknown enum operations.
Enumerate operations your code passes and confirm they exist in your engine version's provider switch.
Wrap validateAction in a compatibility helper when supporting multiple engine versions.

When it happens

Trigger: Calling securityProvider.validateAction with a RepositoryOperation constant outside the handled cases (e.g. an operation added in a newer Kettle version while using an older KettleFileRepositorySecurityProvider, or null/custom operation).

Common situations: Mixing Kettle engine versions (plugins or embedding code compiled against a newer engine), custom repository code passing unexpected operations, upgrade regressions.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/repository/filerep/KettleFileRepositorySecurityProvider.java:112

          break;

        case MODIFY_SLAVE_SERVER:
        case MODIFY_CLUSTER_SCHEMA:
        case MODIFY_PARTITION_SCHEMA:
          if ( capabilities.isReadOnly() ) {
            throw new KettleException( operation + " : repository is read-only" );
          }
          break;
        case DELETE_SLAVE_SERVER:
        case DELETE_CLUSTER_SCHEMA:
        case DELETE_PARTITION_SCHEMA:
          if ( capabilities.isReadOnly() ) {
            throw new KettleException( operation + " : repository is read-only" );
          }
          break;

        default:
          throw new KettleException( "Operation [" + operation + "] is unknown to the security handler." );

      }
    }
  }

  public boolean isReadOnly() {
    return capabilities.isReadOnly();
  }

  public boolean isLockingPossible() {
    return capabilities.supportsLocking();
  }

  public boolean allowsVersionComments( String fullPath ) {
    return false;
  }

  public boolean isVersionCommentMandatory() {

View on GitHub (pinned to f3058517a1)