Community
Technology Blog Posts by SAP
cancel
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Showing results for 
Search instead for 
Did you mean: 
Read only

🛠️ Simplified Sync Troubleshooting: A Quick Guide to Analyze SAP Commerce Synchronization Issues

sabrinabarbosa27
Associate
Associate
4 weeks ago
0 Likes
589

Can't figure out why your SAP Commerce catalog synchronization has stalled? 
This guide is your friendly roadmap to tackling those tricky synchronization jobs and cronjob issues.
We'll walk you through simple diagnostic steps, key configurations, and smart performance tips to make sure your product data moves smoothly.

💡Core Diagnostics & Status Checks

These are the immediate actions you should take when a synchronization job fails or stalls:

  1. Verify the Cronjob Status: Always check the current synchronization status. If a cronjob runs for hours without noticeable progress, manually set its status to ABORTED to force-stop it.

  2. JDBC Log + Thread Dump: Needed if the configuration phase is not finishing due to long-running queries or complex data models.
  3. Check for Concurrent Syncs: Ensure only one full synchronization is running at a time. The system prohibits partial syncs during a full sync. Clean up any cronjobs that share the same source/target versions and are stuck in NEW, CONTINUED, or RUNNING statuses. 

    There are some points to consider when starting an A catalog synchronization job:

    • if another B.fullSync == true sync job is running --> failure ("Cannot perform partial sync cron job when there is other full sync cron job running")

    • if A.fullSync == true, and any other sync is running --> failure ("Cannot perform full sync cron job when others are running")

    • if A.fullSync == false, and no other sync is running --> success

    • if A.fullSync == false, and there is another sync B with B.fullSync == false is running -> compare schedules:

      • overlap --> failure ("Cannot perform partial sync when there are items overlapping from other running cron job")

      • The number of items exceeds the limit (catalog.sync.partial.max.items default value set to 500) --> failure ("Cannot perform partial sync when number of items to sync exceed the limit")

      • no overlap --> success

  4. Analyze Synchronization Logs:

    • Look for critical messages in your logs, taking always in consideration the Cronjob ID to analyze the error.

    • Examine the configuration phase output to confirm how many items are scheduled and if this phase completes successfully. If you notice that there is no information about finished configuration phase you should be looking at your configured Root types.

    • Review the synchronization phase flow for the number of passes, items processed, and any reported errors. If the errors raised, does not contain important information about the data sync, is necessary to enable Debug level logs.

🔍Deep Logging and Items Analysis

To capture the detailed information needed to pinpoint the root cause of an error, temporarily adjust your logging configuration.

  1. Enable DEBUG Logs for Synchronization: Turn on DEBUG level logging for the synchronization process to trace detailed execution steps.

    Properties:
    log4j2.logger.synchronization.name = de.hybris.platform.catalog.jalo.synchronization
log4j2.logger.synchronization.level = debug
log4j2.logger.synchronization.appenderRef.stdout.ref = STDOUT

    • Tip: If exceptions are "swallowed," enable stack trace logging: synchronization.itemcopycreator.stacktraces=true.

    • Crucial Note: Disable DEBUG logging immediately after investigation to prevent performance degradation from excessive log file generation.

  2. Identify Problematic Items: If an error includes a PK (Primary Key), use the HAC PK Analyzer tool to quickly identify the Typecode (the item type) of the problematic data.

  3. Analyze Sync Media Dumps: If the synchronization finishes with errors or unfinished items, analyze the synchronization media dumps to list exactly which items failed.

⚙️Data Integrity & Performance Optimization

Focus on known structural and performance bottlenecks, particularly involving data model constraints and database interaction.

  1. Data Integrity Checks:

    1. Review ItemSyncTimestamps Table: This table tracks the sync status of item pairs. Query it for bad data:

    2. Check for targetitem is null or targetitem equals sourceitem (indicating a loop).

    3. If corruption is suspected, enable the forceUpdate flag to force item recreation.

    4. Last Resort: If corruption is severe, clean the ItemSyncTimestamps for the problematic versions. The next sync will run as a complete initial sync.

  2. Mandatory Attributes: If synchronization fails due to a MandatoryAttributesValidator error, it means an item has a null value for an attribute defined as mandatory. This often happens after an attribute's definition is changed from optional to mandatory. Fix the existing source data to provide the missing value. 

  3. Deadlocks:  The HybrisOptimisticLockingFailureException and related deadlocks are a common sign of concurrent modification during the synchronization process. While locking is a normal part of processing, excessive locking hurts performance.

    1. Understanding the Error: This exception often arises when multiple sync workers try to modify the same item concurrently.
    2. It is not always a true failure: as explained in KBA 2987513, the data import might succeed in later synchronization rounds. The job might fail overall simply because too many of these exceptions occurred, even if the data was eventually loaded.
    3. Vast numbers of deadlocks cause the system to initiate additional synchronization rounds to resolve the item updates. As long as logs aren't flooded with these (they are often tracked as "deadlocks: X items dumped"), there's usually no immediate concern.
  4. Adjust Worker Count (Testing Progress): 

    1. In most cases, reducing the number of sync workers (via catalog.sync.workers) can resolve the issue by lowering concurrency, although overall performance may drop slightly.

    2. Crucial Diagnostic Step: Temporarily set the number of sync threads to 1 to see if the sync completes or progresses without deadlocks. This isolates the problem, confirming if concurrency is the root cause.

  5. Performance improvements: Synchronization is heavily database-dependent. Performance often hinges on the database's ability to handle the load.
    1. Add Indexes: Check for missing indexes on types with specific unique catalog keys. Use JDBC logging to find slow queries.
    2. Remove Indexes: Analyze and remove unused database indexes.
    3. Monitor Database: Monitor CPU, memory, disk I/O, and network I/O between the application and database servers.
    4. DB Maintenance: Perform routine database maintenance, such as rebuilding table statistics and checking for fragmented indexes, especially after large data imports.
    5. Data simplification: Remove unnecessary attributes from the sync configuration. For example: Orders, supported languages and PriceRows attributes are highly dependent of the data model so the performance could be impacted.

 

📚Key KBAs For Synchronization Troubleshooting

Here is a quick reference list of essential Knowledge Base Articles (KBAs) that explain the points mentioned in more detail:

KBA NumberIssue AddressedPurpose
2987565Synchronization Job and Cronjob IntroductionProvides fundamental concepts for understanding how sync jobs operate.
3455775Synchronization Cronjob FailureSpecific resolution for the critical error: "all workers died - aborting sync".
3130989How to enable additional loggingInstructions for turning on DEBUG level logging for synchronization (crucial for root cause analysis...
2911856How to reveal exception and stacktraceGuides on how to reveal swallowed exceptions and stack traces for the synchronization process (for v...
3196657HybrisOptimisticLockingFailureExceptionExplains that this exception is often not a true data failure, and data is usually imported successf...
3084142How to detect corrupted data of non-existing itemsProvides methods to find and clean up corrupted data (ghost PKs) in the ItemSyncTimestamps table.
3140267Product synchronization creates new PKsProvides guidance when modifying a Base Product inadvertently leads to new PKs for existing products...
3547346Improving prices Synchronization processDetails on the best practices for decoupling PriceRows to improve overall sync performance.
2671624How to make data model attributes synchronizableExplains how to include or exclude attributes from synchronization to simplify the data model and bo...
2497134How to run a synchronization job with restrictionsExplains how search restrictions can unintentionally prevent items from being synchronized.
3381781Sync job aborted caused by high number of productsProvides the resolution for performance issues caused by high cardinality (too many products assigne...
3023423Synchronization automatically triggered with forceUpdateExplains why the forceUpdate flag may be automatically enabled by certain Backoffice actions (since ...
3571184How to create Synchronization cronjobGuidance on the proper way to set up synchronization runs, especially regarding assigning triggers t...


🪄 Now your Catalog is Ready to Go!

You now have a complete next action plan for future sync situations!
Just follow this step-by-step guide: check your logs, apply a specific fix, and your catalog items will move smoothly and fast from staging to your live site 😄