If you're using Instrumentl's Salesforce Integration, Raiser's Edge NXT Integration, or Virtuous Integration, you might encounter a specific error when mapping fields or syncing records. Errors often arise from conflict with various rules, requirements, or permissions set forth within these platforms.
The following guide explains the error codes for each integration and offers recommended resolutions.
Salesforce
While troubleshooting, you may also wish to reference our Salesforce Integration guide and FAQs. You can jump to a specific error type using the table below:
|
|
OP_WITH_INVALID_USER_TYPE_EXCEPTION
You may be attempting to sync a Task in Instrumentl to a record in Salesforce that is assigned to an Instrumentl user who does not have access to that record in Salesforce. This typically occurs when tasks are configured to sync to an object (such as a Task or Activity) that the assigned user doesn't have permission to create or edit.
Recommended actions:
Update this user's permission in Salesforce. Re-run the sync.
OR
Assign the Task in Instrumentl to a different user. Re-run the sync.
INVALID_CROSS_REFERENCE_KEY
The record has a required association (e.g., a Task may require that an assignee is set, but this field is not mapped in Instrumentl).
Potential causes:
The field is marked as required in Salesforce, but is neither mapped nor set in Instrumentl. Please review mappings in Salesforce integration setup in Instrumentl.
OR
The field is populated in Instrumentl, but there's no association in Salesforce. This may be because the record has been deleted in Salesforce.
OR
The user doesn't have access to the associated record in Salesforce. See further details here.
OR
Faulty process builder setting in Salesforce: This occurs when an automation in Salesforce updates a record you do not have access to.
INVALID_FIELD
The column doesn't exist in Salesforce, but may have existed at the time of mapping.
Recommended actions:
In Setup > Object Manager > Account > Fields & Relationships, create (or undelete) the field with the name exactly {field name} and the expected data type. Re-sync in Instrumentl.
OR
Remap the field to a new field in the Salesforce integration setup in Instrumentl.
DUPLICATES_DETECTED: Similarly named account identified
Syncing this record violates your user-created duplicate rule settings in Instrumentl.
Recommended actions:
Change your duplicate rules in Salesforce to make similar Account names more permissive.
OR
Create a Salesforce Account with a unique name and link Instrumentl to the record.
CIRCULAR_DEPENDENCY: A parent account can't be the child of an account it's already a parent of.
You’re attempting to create an Account hierarchy loop (A → B → C → A). However, Salesforce forbids circular parent-child relationships.
To resolve this issue:
Decide which single chain of parents you prefer most.
In the offending Accounts, clear the Parent Account field (or set it to a different, non-descendant account).
Retry the sync in Instrumentl.
FIELD_INTEGRITY_EXCEPTION: {object}: id value of incorrect type: {id type}
There are three common causes for this error:
Invalid Field Value: Assigning an invalid value to a field.
Validation Rule Violation: Violating field-level validation rules.
Data Type Mismatch: Providing a value that doesn't match the field's data type or constraints.
For example, attempting to assign a non-existent country code to a country field that uses a picklist of valid country codes would trigger this exception.
INVALID_TYPE: sObject type {name of field} is not supported
This means you're either trying to sync a field that may no longer exist or a field you do not have permission to update.
You can resolve this by confirming that the field reference still exists in Salesforce and that you have permission to set or update the field in this context.
INVALID_FIELD_FOR_INSERT_UPDATE
When you're trying to create or update a record, you're including a field that:
Can’t be changed manually (it's read-only);
Doesn’t exist on that object; or
Is only available in specific contexts (e.g., only during creation, not updates).
Common Causes:
Trying to set system fields like
CreatedDateorLastModifiedById.Misspelling a field name.
Using a field that your user/profile doesn’t have permission to access.
Trying to update a formula or auto-generated field.
Recommended solutions:
Make sure the field is editable and available for your user.
Make sure the field is not read-only or restricted.
FIELD_CUSTOM_VALIDATION_EXCEPTION
This error occurs when a custom validation rule in Salesforce fails while trying to save a record. This is either due to required fields being missing or invalid, or data values violating custom validation logic.
E.g., "Age" must be > 18, or all completed tasks must have a type associated with them.
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST
This message indicates you're attempting to sync a bad value for a restricted picklist field in Salesforce. A restricted picklist only allows for specific predefined values.
If you send a value from Instrumentl that’s not on that list, or if you are not syncing over a value that is required, Salesforce will reject it with this error.
REQUIRED_FIELD_MISSING: {Object} is missing the required field {field name}
A field that is marked as required in Salesforce was not populated during the sync. This can happen even if the field is mapped in Instrumentl if the Instrumentl value for that field is blank.
Note: Instrumentl applies fallback values for some blank required fields—text fields fall back to "N/A", currency fields to 0, and date fields to the end of the fiscal year. If none of these fallbacks apply, the sync will fail with this error.
Recommended actions:
Review your Salesforce field mappings in Instrumentl and confirm that all required fields are mapped to an Instrumentl field that will have a value.
If the field is optional in your workflow, consider making it non-required in Salesforce.
STRING_TOO_LONG: {field name} exceeds Salesforce's {character limit} character limit
A value being synced from Instrumentl exceeds the maximum character length configured for that field in Salesforce.
Recommended actions:
Shorten the value in Instrumentl and re-run the sync.
OR
Increase the character limit for that field in Salesforce Setup under Object Manager > [Object] > Fields & Relationships.
FIELD_FILTER_VALIDATION_EXCEPTION: {Object} does not exist or match a Salesforce filter criteria
A record being synced doesn't satisfy a field filter or lookup filter set up in Salesforce. This often occurs when a lookup field has filter criteria that the synced value doesn't meet.
Recommended actions:
Review your Salesforce lookup filter settings for the field referenced in the error and confirm that the value being synced from Instrumentl is a valid match.
Contact your Salesforce admin to adjust or remove the filter criteria if it is blocking valid data.
invalid_grant: expired access/refresh token
Instrumentl's connection to your Salesforce account has expired or been revoked. This can happen if your Salesforce session times out, your password changes, or your connected app authorization is removed.
Recommended actions:
Go to your Salesforce integration settings in Instrumentl.
Disconnect and reauthenticate your Salesforce account.
Re-run the sync.
Raiser’s Edge NXT
While troubleshooting, it may also be useful to reference our RENXT Integration guide & FAQs. You can jump to a specific error code using the table below:
Error # | Message |
| |
| |
| |
|
Unable to validate your Raiser's Edge NXT configuration; please review your integration settings or contact support for help
When setting up your initial RENXT configuration, even if your RENXT account has been authorized & successfully linked to your Instrumentl account, you must still map all fields in order to complete your configuration.
Recommended actions:
First, double-check that your accounts were linked successfully:
In your integration settings, open Step 1: "Authorize Raiser's Edge NXT" to verify whether your Raiser's Edge and Instrumentl accounts are properly linked.
You can confirm your authorization status by checking for the green highlighted message: "You've successfully connected your Raiser's Edge NXT account to Instrumentl.":
IF SO:
If your accounts were linked successfully, your integration is likely not fully configured because you have not mapped all fields.
Review steps 2-4 and ensure you've mapped all Opportunity, Funder, and Task Data fields:
Once all fields are mapped, your account's configuration should now be complete.
ELSE:
Contact Instrumentl Support or your Blackbaud Administrator if:
Your accounts were not successfully authorized in step 1, and you are still unable to link them.
Your accounts were successfully connected per step 1, you've mapped all fields in steps 2-4, but the configuration error persists.
1006: The requested proposal record does not exist
The record you are trying to sync to does not exist in Raiser's Edge NXT. It may have been deleted.
Note: If this error occurs during an automatic background sync, Instrumentl will automatically unlink the record and send you a notification: "External object does not exist in CRM. Record has been unlinked." This is expected behavior — the link is removed because the record no longer exists in RE NXT.
Recommended actions:
In Instrumentl, sync to a different existing record in RE NXT.
OR
In Instrumentl, create a new record.
403: The user does not have permission to perform this operation
The user does not have permission to perform this operation. Please check with your RENXT admin about your permissions.
25002: No user mapping exists for user identifier {identifier ID} and tenant {tenant ID}.
You may be logged out of Raiser's Edge, or your SSO session has expired. Please try disconnecting and reauthenticating the integration in Instrumentl.
Virtuous
While troubleshooting, it may also be useful to reference our Virtuous Integration guide & FAQs.You can jump to a specific error type using the table below.
Note: Four of the five Virtuous Integration errors below do not have specific error codes/messages. In these instances, the integration fails silently, which is why they're worth mentioning.
Error | Message |
| |
(Grant status is not mapped to a Virtuous status.) | |
(Contact name, Contact type, or Grant name is blank.) | |
(Grant cannot sync because the linked Funder (Contact) hasn't been synced yet.) | |
(Contact or Grant was deleted in Virtuous; the record has been unlinked in Instrumentl.) |
Your Virtuous API key is invalid. Please update your API key to connect to your Virtuous account.
Instrumentl is unable to connect to Virtuous because the API key on file is no longer valid. This typically happens if the API key was revoked or regenerated in Virtuous.
Note: Unlike Salesforce and Raiser's Edge, Virtuous uses an API key (not OAuth) to authenticate. Virtuous API keys can last up to 15 years, so this error is uncommon—but it can occur if the key is manually revoked or your Virtuous account changes.
Recommended actions:
Log in to your Virtuous account and navigate to your API settings to verify that your API key is still active.
If the key has been revoked or changed, generate a new one in Virtuous and re-enter it in your Virtuous integration settings in Instrumentl under "Step 1: Authorize Virtuous."
Unmapped Status: Grant status is not mapped to a Virtuous status
A grant status in Instrumentl has not been mapped to a corresponding status in Virtuous. When Instrumentl attempts to sync a grant with an unmapped status, the sync will fail.
Recommended actions:
Go to your Virtuous integration settings in Instrumentl.
Review your status mappings and ensure every Instrumentl status (Researching, Planned, LOI In Progress, etc.) is mapped to a Virtuous grant status.
Re-run the sync once all statuses are mapped.
Missing Required Fields: Contact name, Contact type, or Grant name is blank
A record is missing a field that Virtuous requires in order to create or update it. In Virtuous, the following fields are always required:
Contact (Funder): Contact name and Contact type
Grant: Grant name
If these fields are blank when Instrumentl attempts a sync, the sync will fail.
Recommended actions:
Confirm that the funder and grant names are populated in Instrumentl.
Re-run the sync.
Contact Does Not Exist: Grant cannot sync because the linked Funder hasn't been synced yet
Virtuous requires that the Contact (Funder) record exist before a Grant can be created and linked to it. If you attempt to sync a grant before its associated funder has been synced to Virtuous, the sync will fail because there is no Contact to attach the Grant to.
Recommended actions:
First, sync the Funder to Virtuous to create the Contact record.
Once the Funder is successfully synced, re-run the sync for the Grant.
Record Deleted in Virtuous: Contact or Grant was deleted; record has been unlinked in Instrumentl
If a Contact or Grant previously synced in Virtuous is deleted, the next time Instrumentl attempts to sync that record, it will detect that the record no longer exists. Instrumentl will automatically unlink the record and send you a notification: "External object does not exist in CRM. Record has been unlinked."
This is expected behavior — the link is removed because the record it points to has been deleted in Virtuous.
Recommended actions:
If the deletion was intentional, you can re-sync the record from Instrumentl to create a new Contact or Grant in Virtuous.
OR
If the deletion was accidental, restore the record in Virtuous first, then re-link it in Instrumentl by selecting the existing record when syncing.
If you've attempted the resolutions above and the error persists, you may wish to contact either your CRM's administrator or Instrumentl, depending on the issue.
Contact Us 
If you have any general questions about your CRM integration with Instrumentl, please reach out to our friendly Support team. Simply start a conversation using Messenger or email us at hello@instrumentl.com.