Loading
Help Agent Performance DegradationRead More

Salesforce SOQL Relationship Query (__r) Not Recognized in MuleSoft Salesforce Query Connector

Publish Date: Jan 27, 2026
Description

The MuleSoft Salesforce Query Connector executes SOQL queries using the permissions of the configured Salesforce integration user. If this user lacks access to the objects, fields, or relationship metadata referenced in the query, Salesforce returns an error indicating the relationship is not recognized.

This behavior can be misleading because:

  • The SOQL query works in Salesforce UI tools using a System Administrator user
  • The same query fails when executed via MuleSoft using an API/integration user
  • The error appears to suggest a syntax or connector limitation, when it is actually permission-related

Error Message

org.mule.extension.salesforce.internal.error.exception.service.InvalidRequestDataException: Didn't understand relationship 'AssetWarranties__r' in FROM part of query call. If you are attempting to use a custom relationship, be sure to append the '__r' after the custom relationship name.

Root Cause

The Salesforce integration user configured in MuleSoft does not have sufficient permissions to access:

  • One or more objects involved in the relationship query
  • Fields referenced in the SOQL query
  • The relationship metadata itself (child relationship access)

This commonly occurs when:

  • An API-only or restricted profile is used
  • Required Permission Sets are missing
  • Field-Level Security (FLS) is not granted for queried fields
  • Custom object permissions (e.g., AssetWarranty__c) are not assigned

 

Resolution

Step 1: Identify the Integration User

  • Open the MuleSoft Salesforce Connector configuration
  • Identify the Salesforce username used for authentication
  • Confirm whether it differs from the user used in Salesforce Inspector or Developer Console

Step 2: Compare Permissions

Compare the integration user with a working user (typically System Administrator):

  • Object permissions (Read access)
  • Field-Level Security (Read access)
  • Assigned Permission Sets

Step 3: Grant Required Permissions

  1. Navigate to Salesforce Setup → Object Manager

  2. Open each object referenced in the SOQL query (parent and child)

  3. Go to Fields & Relationships

  4. For each queried field:

  • Click Set Field-Level Security
  • Grant Read access to the integration user’s profile or permission set
  • Ensure Read access is granted for all related custom objects (e.g., AssetWarranty__c)

Assign Appropriate Profile or Permission Set

Clone the System Administrator profile and tailor it for integrations
or Create a dedicated “MuleSoft Integration” Permission Set and assign:

  • Object access
  • Field-level access
  • Relationship access

The issue was resolved by aligning the MuleSoft integration user’s permissions with those of the Salesforce UI user. Assigning the System Administrator profile and granting permissions to the AssetWarranty object and related fields allowed the __r relationship queries to execute successfully through the MuleSoft Salesforce Query Connector.

 

Additional Resources
Knowledge Article Number

005299561

 
Loading
Salesforce Help | Article