Common Issues
This guide covers frequently encountered problems when using Cloud Replicator and their solutions.
Replication Not Starting
Symptom
Manual Run or scheduled job doesn't start replication.
Possible Causes and Solutions
No Active Table Mappings
- Check Table Mapping page
- Ensure at least one mapping has Active = Yes
- Or use "Manual Run (Selected)" for inactive mappings
License Issue
- Production environments require valid license
- Check license status in Cloud Replicator Setup
- Register or renew license if needed
Engine Count Set to Zero
- Open Cloud Replicator Setup
- Verify Replication Engine Count > 0
- Default is 10
No Companies Match Filter
- Review Company Filter on table mappings
- Ensure at least one company matches
- Leave blank to include all companies
No Data Appearing in Destination
Symptom
Replication completes but destination is empty.
Possible Causes and Solutions
Company Filter Too Restrictive
- Check Company Filter setting
- Test with empty filter (all companies)
- Verify company names match exactly
Table Has No Data
- Verify source table contains records
- Check in correct company
- Run Business Central query to confirm
Credentials Incorrect
- Verify storage account/service names
- Re-enter access keys
- Test credentials in Azure Portal
Wrong Destination Checked
- Confirm which destination is configured
- Verify you're checking the right Azure resource
- Check default destination in Setup
Replication Fails with Errors
Symptom
Replication Log shows Failed status with error message.
Common Errors and Solutions
"Connection Refused" or "Unable to Connect"
- Verify network connectivity
- Check Azure service is available
- Review firewall settings on Azure resource
- Ensure Business Central can reach Azure endpoints
"401 Unauthorized" or "403 Forbidden"
- Access key is invalid or expired
- Regenerate key in Azure Portal
- Update key in Cloud Replicator Setup
- Check key permissions
"404 Not Found"
- Table/container doesn't exist (usually auto-creates)
- Database name incorrect (Cosmos DB NoSQL)
- Service name incorrect
"429 Too Many Requests"
- Cloud service is throttling
- Reduce replication engine count
- Increase retry delay in Setup
- Increase Cosmos DB RU/s if applicable
"Request Entity Too Large"
- Record data exceeds limits
- Exclude large blob fields
- Reduce unfolded data
Slow Replication Performance
Symptom
Replication takes longer than expected.
Possible Causes and Solutions
Too Few Engines
- Increase Replication Engine Count
- Consider enabling table splitting
- Monitor Engine Pulse for utilization
Large Tables Without Splitting
- Enable Use Table Splitting in Setup
- Configure Maximum Records per Engine
- Run initial load during off-hours
Too Many Fields
- Add Field Actions to exclude unnecessary fields
- Reduce unfold depth
- Exclude blob fields
Cloud Throttling
- Check cloud destination limits
- Increase provisioned throughput (Cosmos DB)
- Upgrade service tier if needed
Network Latency
- Ensure Azure resource is in same region
- Check for network issues
- Consider timing of replication
Data Missing or Incorrect
Symptom
Some records or fields are not appearing correctly.
Possible Causes and Solutions
Field Excluded by Action
- Check Field Actions for the table
- Remove or change Exclude action
- Verify field is not accidentally excluded
Related Data Not Unfolding
- Check Field Action configuration
- Verify Related Table is set correctly
- Check Global Filter isn't too restrictive
Records Not Updating
- Check Rollback Time setting
- Reset Last Replication if needed
- Verify SystemModifiedAt is updating
Deletions Not Appearing
- Enable Replicate Deletions on table mapping
- Enable Change Log for the table
- Verify Change Log captures deletions
License Issues
Symptom
License-related error messages.
Possible Causes and Solutions
"License Required"
- Production environment needs registration
- Contact Hougaard for license
- Use sandbox for evaluation
"License Expired"
- Renew license before expiration
- Contact Hougaard for renewal
- Re-register with new key
Cannot Connect to License Server
- Transient network issue
- Previously validated license continues working
- Try registration again later
Job Queue Issues
Symptom
Scheduled replication not running as expected.
Possible Causes and Solutions
Job Not Starting
- Check Job Queue Entry status
- Verify schedule configuration
- Ensure Job Queue is running in BC
Job Fails Immediately
- Check Job Queue Log for errors
- Verify user permissions
- Review license status
Jobs Overlapping
- Previous job not completing in time
- Reduce frequency
- Stagger start times
- Increase engine count for faster completion
Azure-Specific Issues
Azure Table Storage
Table Name Invalid
- Special characters in table name
- Cloud Replicator sanitizes automatically
- Check error message for specific issue
Partition Key Too Long
- Company name + postfix exceeds limit
- Shorten Partition Key Postfix
- Configure Exclude Characters
Cosmos DB
Database Not Found
- Create database in Azure Portal
- Verify database name in Setup
- Check for typos (case-sensitive)
Collection/Container Not Created
- Should auto-create
- Check RU/s are sufficient
- Verify permissions
RU/s Exhausted
- Increase provisioned throughput
- Enable Autoscale
- Reduce engine count
Azure AI Search
Index Creation Fails
- Check Admin key permissions
- Verify service name
- Review field type compatibility
SystemId Not Set
- AI Search requires SystemId as RowKey
- Enable on table mapping
- This is forced automatically
Getting More Information
Check Replication Log
Always start troubleshooting by reviewing:
- Open Replication Log
- Filter for Failed status
- Review Error Message
- Note timestamp for correlation
Check Engine Pulse
For stuck replications:
- Open Engine Pulse List
- Look for Stale engines
- Note which table/company is affected
Enable Debug Mode
For detailed investigation:
- Enable "Replicate in Debug Mode" in Setup
- Run Manual Replication
- Watch output in foreground
- Disable after troubleshooting
Warning: Debug mode blocks your session during replication.