Understanding KatanaPIM Sync Process

Symptoms:

• "Test Credentials" button shows error
• Sync operations fail immediately

Solutions:

1. Verify credentials:

   • Check URL is correct (including https://)
   • Verify API key is valid and not expired
   • Ensure no extra spaces in fields

2. Check network:

   • Verify server can reach KatanaPIM URL
   • Check firewall rules allow outbound connections
   • Test with curl from command line

3. SSL issues:

   • Ensure valid SSL certificate on PIM
   • Check PHP has updated CA certificates

Symptoms:

• Products grid stays empty after sync
• Sync completes but no products appear

Solutions:

1. Check product import enabled:

   • Product Data → General → Enable Product Import = Yes

2. Verify store filter:

   • General → Import Settings → Store Filter
   • Ensure correct store is selected or "All"

3. Check PIM has products:

   • Log into KatanaPIM and verify products exist
   • Ensure products are published/active in PIM

4. Review Sync Log:

   • Check for errors in Katana PIM → Sync Log

Symptoms:

• Products appear in KatanaPIM grid
• But no Magento products are created

Solutions:

1. Manual creation required:

   • If auto-create is disabled, use mass action "Update/Create Magento Products"

2. Check automation settings:

   • Automation → Auto create new products = Yes

3. Verify attribute mapping:

   • Required attributes must be mapped (Name at minimum)
   • Check Attributes grid for mapping status

4. Check for errors:

   • Look at "Has Error" in Products grid
   • Review Sync Log for detailed errors

Symptoms:

• Product created but attributes are empty
• Some attributes missing

Solutions:

1. Check attribute mapping:

   • Go to Katana PIM → Attributes
   • Verify attributes are mapped (not "-- Not Mapped --")
   • Ensure attributes are not marked as Skipped

2. Import attributes first:

   • Click "Import Attributes" button
   • Wait for import to complete
   • Then map attributes

3. Verify PIM data:

   • Check product has values for those attributes in PIM

Symptoms:

• Products created but no images
• Assets grid shows errors

Solutions:

1. Check products exist:

   • Assets require linked products to exist first
   • Create products before syncing assets

2. Verify image URLs:

   • Check Assets grid for valid URLs
   • Ensure images are accessible publicly

3. Check file permissions:

   • Magento must have write access to pub/media

4. Review errors:

   • Check "Has Error" and "Error Message" columns

Symptoms:

• Simple products create but not configurables
• Parent products missing

Solutions:

1. Set configurable attributes:

   • Go to Attributes grid
   • Set "Is Configurable" = Yes for variant attributes (Size, Color)

2. Verify parent/child relationships:

   • Check PIM has correct product hierarchy
   • Parent products must have children linked

3. Sync order:

   • Attributes must be synced and configured first
   • Then sync products

Symptoms:

• Sync never completes
• Browser times out
• Memory errors in logs

Solutions:

1. Use CLI instead:

   bin/magento katana:import:full
   

   CLI has no browser timeout limits.

2. Reduce batch sizes:

   • General → Import Settings → Batch Size Settings
   • Lower the page size values

3. Sync in parts:

   bin/magento katana:import:full --attributes
   bin/magento katana:import:full --categories
   bin/magento katana:import:full --products
   bin/magento katana:import:full --assets
   

4. Increase PHP limits:

   • Increase max_execution_time
   • Increase memory_limit

Symptoms:

• Changed products not updating
• "Needs Update" stays No

Solutions:

1. Use Full Sync:

   • Run full sync to reset hash comparison

2. Force update:

   • Use "Update/Create (force)" mass action

3. Check PIM timestamps:

   • Ensure PIM is updating modification dates

Symptoms:

• Sync doesn't run automatically
• Last sync date never updates

Solutions:

1. Check automation enabled:

   • Automation → Enable Automation = Yes
   • Cron frequencies configured

2. Verify Magento cron:

   bin/magento cron:run
   

3. Check cron schedule:

   SELECT * FROM cron_schedule
   WHERE job_code LIKE '%katana%'
   ORDER BY scheduled_at DESC LIMIT 10;
   

4. Check server cron:

   • Ensure system cron runs Magento cron regularly