Troubleshooting & Limitations - Standard Mode

Summary

Operating the app in Standard Mode aligns your catalog data with native Salesforce Commerce standard architectures. However, this enforces strict validation rules, object platform limits, and precise security requirements.

Use this centralized guide to diagnose common synchronization errors and understand structural platform behaviors.

 

Technical Connection & Framework Errors

HTTP Error 401 / 403 during Picklist Synchronization

  • Symptom: Variant product synchronization logs show metadata failure warnings, or your manual Developer Console check fails to return an HTTP 200 status code
  • Root Cause: The Salesforce Self OAuth Client Credentials connection loopback is misconfigured or lacks access
  • Resolution:
    • Verify that your External Client App has the exact Manage user data via APIs (api) OAuth scope selected
    • Confirm that the Client Credentials Execution User is a live Integration/Admin user with proper permissions to modify metadata
    • Ensure that you manually granted External Credential Principal Access (Salesforce_Self - Default) to the synchronization user
    • Double-check that your Named Credential target URL points exactly to your My Domain root and does not contain any trailing API sub-paths like /services/data

CMS API Endpoint Callout Failures

  • Symptom: Asset transfers fail instantly with explicit API connection errors when trying to push images to your CMS Workspace
  • Root Cause: Your Salesforce organization lacks the required backend microservices entitlement
  • Resolution: This is an internal system flag that cannot be viewed via the setup backoffice. You must open a critical case with Salesforce Support and explicitly ask them to activate the backend feature named Salesforce CMS: PIM integration APIs on your Org ID

 

Object Architecture Limitations

Simple Product to Variant Conversion Block

  • Symptom: The app fails to sync variant products, throwing errors on specific Product2 records
  • Structural Limitation: Salesforce Commerce core architecture strictly enforces a No Conversion rule. A standard, standalone simple Product2 record cannot be converted into either a Variation Parent product or a Variation Child product after creation.
  • Resolution: If product data was previously synchronized as simple products (or mapped into custom tables), you must completely delete those old product records from Salesforce (and empty the Recycle Bin) before initiating a Standard Mode variation transfer.

Salesforce Self Picklist Constraints

  • Structural Limitation: The dynamic picklist injector required for variation axes attributes requires fields on the ProductAttribute object to be configured exclusively with local values
  • Risk: If you created your custom picklist fields using a Global Value Set, the automatic option injection will critically fail, and variants will fail to display on your digital storefronts. Always select Enter values, with each value separated by a new line when deploying attribute fields.

 

Assets & Media Limits

Storefront CSP Policy Violations (Broken Images)

  • Symptom: The app logs indicate successful transfers and CMS records exist, but images appear as broken icons on the live storefront
  • Root Cause: Content Security Policies (CSP) are blocking external domains
  • Resolution: You must explicitly whitelist your Akeneo PIM instance domain root URL under Setup > Trusted URLs and activate the img-src (Images) directive toggle to authorize Salesforce CMS to render the asset payloads

Hard Platform Media Assignment Limits

  • Structural Limitation: Salesforce Commerce applies hard platform limitations on the total number of managed content images or document assets that can be linked to a single Product2 record
  • Behavior: When Akeneo asset assignments exceed these native limits, the app gracefully logs a warning and skips the overflowing media items to prevent the overall product update transaction from rolling back

 

Permission & Metadata Quirks

Readiness Check “False Positives”

  • Symptom: The app's built-in readiness utility displays a green status confirmation, but transfers fail with "Access Denied" or field security exceptions on category or product standard objects
  • Behavior: The package readiness utility checks exclusively for the physical existence of your custom External ID fields. It is structurally incapable of assessing Field-Level Security (FLS) or individual user profile data permissions.
  • Resolution: You must manually edit your Synchronization User profile or custom permission set to ensure full Read/Write access and active FLS are checked for the target standard objects and your three new Akeneo_*_External_Id__c fields

Category Mode Change Asynchronicity

  • Symptom: Saving the change from Akeneo Custom Objects to Standard under Category Target Mode does not instantly reflect in immediate data transfers
  • Behavior: Target mode changes trigger an asynchronous custom metadata deployment in the Salesforce backend. Always allow several minutes for the background metadata job to deploy completely before kicking off bulk transfers.

Want to find out more? Take a look at these related articles