Salesforce - Ampersand

Read Action: `No such column` error

A read fails with an error similar to:

bad request:
field_one__c,field_two__c,example_field__c,field_three__c,field_four__c
                          ^
ERROR at Row:1:Column:26
No such column 'example_field__c' on entity 'Opportunity'. If you are attempting to use a custom field,
be sure to append the '__c' after the custom field name. Please reference your WSDL or the describe call
for the appropriate names.

Which case is this?

Reads work for other customers but fail for this one → almost always a field-level visibility issue. Even System Administrators do not automatically receive visibility for every field.
Reads fail for every customer → the field name itself is more likely the problem.

Resolve a field-level visibility issue

Share the field visibility instructions in the Salesforce customer guide with your customer. That user must be granted Visible field-level visibility for the field, either through their profile or via a permission set. Ampersand pauses reads automatically after repeated failures to avoid overloading Salesforce APIs, so once the field is visible you’ll need to explicitly resume. Call the Unpause Reads endpoint, or reach out to Ampersand support and we can unpause it for you.

Verify the field name

Look up the field in the Salesforce Object Reference. If it’s listed, the field is standard and this is a field-level visibility issue.
If it’s not listed, it’s a custom field. Custom field API names must end with __c. If your read object configuration is missing the suffix, fix it.
If the suffix is already correct, this is a field-level visibility issue.

Write Action: `No such column` error

A write fails with an error similar to:

{
  "operationId": "00000000-0000-0000-0000-000000000000",
  "errors": [
    {
      "message": "error writing account: bad request: No such column 'Testing__c' on sobject of type Account"
    }
  ]
}

Which case is this? Call Get object metadata via installation for the object you’re writing to.

The field isn’t in the response → it doesn’t exist in the customer’s org. Custom fields vary by org.
The field is in the response → the connected user can’t see it.

Field doesn’t exist in the customer’s org

Remove the field from your write payload for this customer, for example by checking object metadata before writing, or by falling back to a default. Longer-term, update your application to handle per-customer schema differences.

Connected user lacks field-level visibility

If the field exists in the org but isn’t visible to the connected user’s profile, Salesforce returns the same No such column error. Follow the steps in Resolve a field-level visibility issue. Creating an installation with subscribe actions fails with an error similar to:

You can't select more entities. You've exceeded the maximum number of unique
Change Data Capture selected entities. Your total number of entities includes
the ones selected here and through custom channels. (errorCode: LIMIT_EXCEEDED)

By default, a Salesforce instance allows Change Data Capture on at most five entities. Entities your customer has selected through custom channels count toward the same limit, so the ceiling can be reached before your integration is installed. You have two ways to resolve this:

Reduce the number of objects your integration subscribes to, so the total stays within the customer’s limit.
Ask your customer to purchase the Salesforce Change Data Capture add-on license, which removes the limit on their instance.

A subscription is healthy and other updates arrive, but changes to one specific field never produce an event. Salesforce only emits change events for direct fields on a record. Derived fields such as LastActivityDate never trigger change events, no matter how they are configured. See Salesforce’s change event documentation for the full list of limitations. Watch a direct field instead, or subscribe to the object whose direct fields capture the change you care about.

Connection shows `bad_credentials` after working previously

An integration that used to work starts failing: proxy requests return 401, reads and writes fail, and the connection’s status is bad_credentials.

Which case is this?

Failing for every customer → most likely your External Client App is misconfigured or shared across projects.
Failing for one customer → most likely a token policy or revoked access on their side.

Check your External Client App

Confirm the app requests the refresh_token scope. Without it, Salesforce issues an access token that expires and cannot be renewed. Review your configuration against Create External Client App. Also confirm you are not reusing one app across multiple Ampersand projects. Each project should have its own app.

Check the customer’s Salesforce settings

Two customer-side settings commonly invalidate credentials:

Refresh token policy. If their policy expires refresh tokens after a set period, credentials break on that schedule. Ask them to set the policy to Refresh token is valid until revoked in the app’s OAuth policies.
Revoked access. A Salesforce admin can revoke an app from the OAuth Connected Apps Usage page. Ask their admin to confirm the app has not been revoked.

Once resolved, your customer can reconnect from the Manage tab. See Update a connection.

Salesforce returns `INVALID_SESSION_ID`

An API call fails with an error similar to:

{
  "message": "This session is not valid for use with the specified REST API endpoint. One of the following scopes is required: Full access, Manage user data via APIs, Access Connect REST API resources",
  "errorCode": "INVALID_SESSION_ID"
}

Work through these in order:

Confirm the connection’s scopes include both api and refresh_token. If either is missing, correct your External Client App configuration.
Confirm you are not using the same app across multiple projects.
Check for duplicate connections for the same customer. Connecting the same Salesforce instance twice invalidates the earlier refresh token, so the first connection stops working. Delete the duplicates.

If none of those apply, ask your customer to uninstall and reinstall the integration, following the Salesforce customer guide.

Read fails with `too many junction ids`

A read of EmailMessage fails with:

Query is requesting too many junction ids; limit is 500

The query exceeded Salesforce’s limit on junction object lookups. On EmailMessage, the junction fields are ToIds, CcIds, BccIds, and ContentDocumentIds. A single mass email with hundreds of recipients can exceed the limit of 500 on its own.

Which case is this? Check whether you actually need the recipient IDs, or only their addresses.

You only need addresses → remove the junction fields.
You need the IDs → read EmailMessageRelation instead.

Remove the junction fields

Drop the junction fields from requiredFields in your manifest:

requiredFields:
  - fieldName: toids   # remove this

The recipient addresses remain available through toAddress, ccAddress, and bccAddress, so most integrations lose nothing.

Read `EmailMessageRelation` instead

If you need the IDs themselves, add the EmailMessageRelation object to your read action. This is the object that ToIds, CcIds, and BccIds actually refer to, and it exposes the same information without the junction limit:

EmailMessageId
RelationAddress
RelationId
RelationObjectType
RelationType, for example ToAddress, CcAddress, or BccAddress

`OAUTH_APPROVAL_ERROR_GENERIC` in the OAuth window

Your customer sees OAUTH_APPROVAL_ERROR_GENERIC in the Salesforce OAuth window while installing the integration. This is a Salesforce permission issue: the installing user is not allowed to approve the app. Their admin needs to enable one of the following for that user:

Use Any API Client, if their org has API Access Control enabled
Approve Uninstalled Connected Apps, if Use Any API Client is not shown

Both are covered in Required system permissions.

`OAUTH_EC_APP_NOT_FOUND` in the OAuth window

The OAuth window reports that the external client app is not installed in the org.

Which case is this?

Only this customer is affected → they likely never installed the package.
Every customer is affected → your app is likely in the wrong org.

The customer did not install the package

Your customer must open the package install URL and install the package before connecting. Send them the URL described in Build the Package Install URL.

The app was created in the wrong org

The External Client App must be created in your Dev Hub Org, not your Namespace Org. If it was created in the wrong org, no customer can install it. See Salesforce orgs needed.

`Object type is not supported` for a standard object

A read or write fails with an error similar to:

Object type 'contact' is not supported. If you are attempting to use a custom object,
be sure to append the '__c' after the entity name.

When the object named is a standard Salesforce object, this error is misleading. It usually means the connected user does not have permission to access the object, so Salesforce reports it as though it does not exist. Ask your customer’s Salesforce admin to check the connected user’s object permissions:

For a standard profile, see Field permissions for a standard profile.
For a custom profile, see Object and field permissions for a custom profile.

Check Salesforce API quota

When you suspect a customer is hitting Salesforce API limits, you can read their remaining quota through the proxy:

curl --request GET "https://proxy.withampersand.com/services/data/v62.0/limits" \
  --header "Content-Type: application/json" \
  --header "x-amp-proxy-version: 1" \
  --header "x-amp-project-id: YOUR_PROJECT_ID" \
  --header "x-api-key: YOUR_API_KEY" \
  --header "x-amp-integration-name: YOUR_INTEGRATION" \
  --header "x-amp-group-ref: GROUP_REF"

The response includes DailyApiRequests, which shows the org’s daily allocation and how much of it remains.

​Read Action: No such column error

​Resolve a field-level visibility issue

​Verify the field name

​Write Action: No such column error

​Field doesn’t exist in the customer’s org

​Connected user lacks field-level visibility

​Subscribe installation fails with LIMIT_EXCEEDED

​Subscribe events do not fire when a field changes

​Connection shows bad_credentials after working previously

​Check your External Client App

​Check the customer’s Salesforce settings

​Salesforce returns INVALID_SESSION_ID

​Read fails with too many junction ids

​Remove the junction fields

​Read EmailMessageRelation instead

​OAUTH_APPROVAL_ERROR_GENERIC in the OAuth window

​OAUTH_EC_APP_NOT_FOUND in the OAuth window

​The customer did not install the package

​The app was created in the wrong org

​Object type is not supported for a standard object

​Check Salesforce API quota

Read Action: `No such column` error

Resolve a field-level visibility issue

Verify the field name

Write Action: `No such column` error

Field doesn’t exist in the customer’s org

Connected user lacks field-level visibility

Subscribe installation fails with `LIMIT_EXCEEDED`

Subscribe events do not fire when a field changes

Connection shows `bad_credentials` after working previously

Check your External Client App

Check the customer’s Salesforce settings

Salesforce returns `INVALID_SESSION_ID`

Read fails with `too many junction ids`

Remove the junction fields

Read `EmailMessageRelation` instead

`OAUTH_APPROVAL_ERROR_GENERIC` in the OAuth window

`OAUTH_EC_APP_NOT_FOUND` in the OAuth window

The customer did not install the package

The app was created in the wrong org

`Object type is not supported` for a standard object

Check Salesforce API quota