What causes "JobTrans.Exception.UnableToFindRemoteSlaveServer" in pentaho/pentaho-kettle?

Add the named slave server to the job metadata (JobMeta slave servers list) or correct the name in the job entry

pentaho/pentaho-kettle · error · KettleException

JobTrans.Exception.UnableToFindRemoteSlaveServer

Error message

JobTrans.Exception.UnableToFindRemoteSlaveServer

What it means

Thrown by JobEntryTrans.execute when the entry is configured to run the transformation remotely on a named slave server but that slave server cannot be found in the parent job's cluster/slave registry. The configured name (after environment substitution) does not match any registered SlaveServer. Execution aborts before the transformation is sent.

Solutions

Add the named slave server to the job metadata (JobMeta slave servers list) or correct the name in the job entry
Verify the environment variable used in the slave server name resolves to an existing slave at runtime
Re-select the slave server in Spoon so the reference is stored correctly
If remote execution is not intended, clear the remote slave server setting on the entry

Example fix

// before
jobEntry.setRemoteSlaveServerName( "${SLAVE}" ); // SLAVE unset at runtime
// after
jobEntry.setRemoteSlaveServerName( "slave-01" ); // matches a registered SlaveServer
// or validate before execute:
SlaveServer s = jobMeta.findSlaveServer( name );
if ( s == null ) throw new IllegalStateException( "Unknown slave: " + name );

Defensive patterns

Strategy: validation

Validate before calling

String name = jobEntry.environmentSubstitute( jobEntry.getRemoteSlaveServerName() );
if ( name != null && jobMeta.findSlaveServer( name ) == null ) {
  throw new IllegalStateException( "Slave server not registered: " + name );
}

Try / catch

try { jobEntry.execute( result, nr ); } catch ( KettleException e ) { if ( e.getMessage().contains( "slave" ) ) { log.error( "Slave server misconfigured: " + e.getMessage() ); } throw e; }

Prevention

Register all slave servers in the job metadata
Verify variables in slave names resolve at runtime
Re-select slaves in Spoon after cluster changes
Test remote execution in staging before production

When it happens

Trigger: remoteSlaveServerName is set on the trans job entry, environmentSubstitute resolves it, but parentJob.getJobMeta().findSlaveServer(name) returns null — the name is not defined among the job's slave servers.

Common situations: Typo in the slave server name; slave server defined in a shared meta store not loaded with the job; variable used for the slave name resolves to a wrong/unset value on a different environment; cluster definition removed after the entry was configured.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at engine/src/main/java/org/pentaho/di/job/entries/trans/JobEntryTrans.java:945

            clustering = executionConfiguration.isExecutingClustered();
            remoteSlaveServer = executionConfiguration.getRemoteServer();
            doFallback = false;
          } catch ( KettleException e ) {
            log.logError( e.getMessage(), getName() );
            result.setNrErrors( 1 );
            result.setResult( false );
            return result;
          }
        }

        if ( doFallback ) {
          // Figure out the remote slave server...
          //
          if ( !Utils.isEmpty( remoteSlaveServerName ) ) {
            String realRemoteSlaveServerName = environmentSubstitute( remoteSlaveServerName );
            remoteSlaveServer = parentJob.getJobMeta().findSlaveServer( realRemoteSlaveServerName );
            if ( remoteSlaveServer == null ) {
              throw new KettleException( BaseMessages.getString(
                PKG, "JobTrans.Exception.UnableToFindRemoteSlaveServer", realRemoteSlaveServerName ) );
            }
          }
        }


        // Execute this transformation across a cluster of servers
        //
        if ( clustering ) {
          executionConfiguration.setClusterPosting( true );
          executionConfiguration.setClusterPreparing( true );
          executionConfiguration.setClusterStarting( true );
          executionConfiguration.setClusterShowingTransformation( false );
          executionConfiguration.setSafeModeEnabled( false );
          executionConfiguration.setRepository( rep );
          executionConfiguration.setLogLevel( transLogLevel );
          executionConfiguration.setPreviousResult( previousResult );

View on GitHub (pinned to f3058517a1)