{"record":{"id":"b202ab16b6c6fdba","repo":"pentaho/pentaho-kettle","slug":"salesforceinput-errorupsert","errorCode":null,"errorMessage":"SalesforceInput.ErrorUpsert","messagePattern":"SalesforceInput\\.ErrorUpsert","errorType":"exception","errorClass":"KettleException","httpStatus":null,"severity":"error","filePath":"plugins/salesforce/core/src/main/java/org/pentaho/di/trans/steps/salesforce/SalesforceConnection.java","lineNumber":863,"sourceCode":"\n          for ( Field f : referenceObjectFields ) {\n            if ( f.isIdLookup() && !isIdField( f ) ) {\n              fieldsList.add( String.format( \"%s:%s/%s\", referenceTo, f.getName(), field.getRelationshipName() ) );\n            }\n          }\n        }\n      }\n      return fieldsList.toArray( new String[fieldsList.size()] );\n    }\n    return null;\n  }\n\n\n  public UpsertResult[] upsert( String upsertField, SObject[] sfBuffer ) throws KettleException {\n    try {\n      return getBinding().upsert( upsertField, sfBuffer );\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"SalesforceInput.ErrorUpsert\", e ) );\n    }\n  }\n\n  public SaveResult[] insert( SObject[] sfBuffer ) throws KettleException {\n    try {\n      List<SObject> normalizedSfBuffer = new ArrayList<>();\n      for ( SObject part : sfBuffer ) {\n        if ( part != null ) {\n          normalizedSfBuffer.add( part );\n        }\n      }\n      return getBinding().create( normalizedSfBuffer.toArray( new SObject[normalizedSfBuffer.size()] ) );\n    } catch ( Exception e ) {\n      throw new KettleException( BaseMessages.getString( PKG, \"SalesforceInput.ErrorInsert\", e ) );\n    }\n  }\n\n  public SaveResult[] update( SObject[] sfBuffer ) throws KettleException {","sourceCodeStart":845,"sourceCodeEnd":881,"githubUrl":"https://github.com/pentaho/pentaho-kettle/blob/f3058517a153da500bf4551f46d79b91bf8ec552/plugins/salesforce/core/src/main/java/org/pentaho/di/trans/steps/salesforce/SalesforceConnection.java#L845-L881","documentation":"KettleException thrown by SalesforceConnection.upsert() when the SOAP upsert call fails. Note the original exception is embedded in the MESSAGE (BaseMessages.getString(PKG, key, e)) rather than as a cause, so the Salesforce fault text appears directly in the error message. It means none/some of the upserted records were processed at the API transport level.","triggerScenarios":"Calling upsert(upsertField, sfBuffer) when the binding throws: invalid external-id field, session invalid, SObject malformed, or Salesforce rejecting the batch (e.g. field infeasible for upsert).","commonSituations":"External ID field not marked as external ID in Salesforce, missing Write/Create permission, record-lock contention during mass upserts, malformed data types (bad date/number formats) in the incoming rows.","solutions":["Read the embedded Salesforce fault in the message — it names the exact field/record problem","Verify the upsertField is a real External ID / custom field marked unique and external","Check integration user has Create and Update object permissions","Validate data formats (dates, picklists, numbers) against the object's field types","Retry with a smaller batch to isolate record-lock/timeout issues"],"exampleFix":"// before\nUpsertResult[] r = connection.upsert(\"ExtId__c\", buffer); // field not external id\n// after\n// In Salesforce setup, mark ExtId__c as External ID + unique, then:\nUpsertResult[] r = connection.upsert(\"ExtId__c\", buffer);\nfor (UpsertResult res : r) if (!res.isSuccess()) logInsertErrors(res.getErrors());","handlingStrategy":"validation","validationCode":"if (upsertField == null || upsertField.isEmpty()) throw new IllegalArgumentException(\"External ID field required for upsert\"); if (sfBuffer == null || sfBuffer.length == 0) throw new IllegalArgumentException(\"Empty upsert buffer\");","typeGuard":"boolean upsertReady(String extField, SObject[] buf) { return extField != null && !extField.isEmpty() && buf != null && buf.length > 0; }","tryCatchPattern":"try { results = connection.upsert(upsertField, buffer); } catch (KettleException e) { log.logError(\"Upsert failed: \" + e.getMessage(), e); throw e; } // fault text is in e.getMessage()","preventionTips":["Mark the external-id field as External ID + unique in Salesforce setup","Verify Create/Update permissions for the integration user","Validate row data types against Salesforce field metadata before upsert","Process in smaller batches to avoid lock timeouts and partial failures","Iterate UpsertResult[] and log per-record errors even on success"],"tags":["salesforce","upsert","api","data"],"backgroundTag":"api-error-response","analyzedSha":"f3058517a153da500bf4551f46d79b91bf8ec552","analyzedAt":"2026-09-13T14:04:16.340Z","contentChangedAt":"2026-09-13T14:04:16.340Z","schemaVersion":2},"datasetVersion":"2026-09-20T23:17:15.980Z"}