What causes "SalesforceInput.UsernameMissing.Error" in pentaho/pentaho-kettle?

Enter the Salesforce username in the step dialog or ensure the referenced variable is defined

pentaho/pentaho-kettle · error · KettleException

SalesforceInput.UsernameMissing.Error

SalesforceInput.UsernameMissing.Error

Error message

SalesforceInput.UsernameMissing.Error

What it means

After validating the URL, the SalesforceConnection constructor checks that a username is present. If getUsername() returns null or empty, it throws a KettleException with key SalesforceInput.UsernameMissing.Error, since Salesforce login requires credentials.

Solutions

Enter the Salesforce username in the step dialog or ensure the referenced variable is defined
Check kettle.properties / environment configuration on the executing machine
Use Test Connection to validate credentials before running the transformation
Confirm the username includes the full Salesforce login (user@example.com, plus sandbox suffix if applicable)

Example fix

// before
username = ${SF_USER}   // undefined
// after
username = integration@example.com
// or define SF_USER=integration@example.com in kettle.properties

Defensive patterns

Strategy: validation

Validate before calling

String user = environmentSubstitute( meta.getUsername() );
if ( user == null || user.trim().isEmpty() ) {
  throw new IllegalStateException( "Salesforce username is empty; set it or define its variable" );
}

Try / catch

try {
  SalesforceConnection conn = new SalesforceConnection( log, url, username, password );
} catch ( KettleException e ) {
  if ( e.getMessage().contains( "UsernameMissing" ) ) {
    fixCredentialsAndRetry();
  } else throw e;
}

Prevention

Define Salesforce credentials in kettle.properties per environment
Use Test Connection to catch missing credentials before execution
Include the full Salesforce username (with sandbox suffix when applicable)
Rotate credentials centrally so fields never go empty

When it happens

Trigger: Constructing SalesforceConnection with no username set in the step metadata, or with a username supplied only via an environment variable that resolves to empty.

Common situations: Empty 'Username' field in the Salesforce step; ${SF_USER} not defined on the executing server; switching to environment-variable config but forgetting kettle.properties entries; SSO/tooling migrations that drop credentials.

Related errors

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

Appendix: source

Thrown at plugins/salesforce/core/src/main/java/org/pentaho/di/trans/steps/salesforce/SalesforceConnection.java:133

    this.qr = null;
    this.startDate = null;
    this.endDate = null;
    this.sObjects = null;
    this.recordsFilter = SalesforceConnectionUtils.RECORDS_FILTER_ALL;
    this.fieldsList = null;
    this.queryResultSize = 0;
    this.recordsCount = 0;
    setUsingCompression( false );
    setRollbackAllChangesOnError( false );

    // check target URL
    if ( Utils.isEmpty( getURL() ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "SalesforceInput.TargetURLMissing.Error" ) );
    }

    // check username
    if ( Utils.isEmpty( getUsername() ) ) {
      throw new KettleException( BaseMessages.getString( PKG, "SalesforceInput.UsernameMissing.Error" ) );
    }

    if ( log.isDetailed() ) {
      logInterface.logDetailed( BaseMessages.getString( PKG, "SalesforceInput.Log.NewConnection" ) );
    }
  }

  public boolean isRollbackAllChangesOnError() {
    return this.rollbackAllChangesOnError;
  }

  /**
   *
   * @see #isRollbackAllChangesOnError(boolean)
   */
  @Deprecated
  public void rollbackAllChangesOnError( boolean value ) {
    setRollbackAllChangesOnError( value );

View on GitHub (pinned to f3058517a1)