Cloud Replicator Documentation
Index

Connection Issues

This guide focuses specifically on troubleshooting connection and authentication problems with cloud destinations.

Connection Error Types

Authentication Errors

Error Meaning
401 Unauthorized Invalid credentials
403 Forbidden Valid credentials but lacking permission

Network Errors

Error Meaning
Connection Refused Cannot reach the service
Connection Timeout Service not responding
DNS Resolution Failed Service name invalid

Service Errors

Error Meaning
404 Not Found Resource doesn't exist
429 Too Many Requests Throttling/rate limiting
500 Internal Server Error Service-side issue
503 Service Unavailable Service temporarily down

Azure Table Storage Connection Issues

Invalid Account Name

Error: Connection refused or DNS resolution failure

Solution:

  1. Verify storage account name in Azure Portal
  2. Use only the account name, not the full URL
  3. Check for typos (all lowercase)

Correct: mystorageaccount Incorrect: mystorageaccount.table.core.windows.net

Invalid Access Key

Error: 401 Unauthorized or 403 Forbidden

Solution:

  1. Navigate to Storage Account > Access keys
  2. Copy the key exactly (no extra spaces)
  3. Paste into Cloud Replicator Setup
  4. Try using the other key (key2 if key1 fails)

Firewall Blocking Access

Error: Connection refused or timeout

Solution:

  1. Navigate to Storage Account > Networking
  2. Check firewall settings
  3. Options:
    • Enable "Allow Azure services" access
    • Add Business Central IPs to allowed list
    • Use Private Endpoint (advanced)

Storage Account Disabled

Error: 403 Forbidden

Solution:

  1. Verify storage account is active
  2. Check Azure subscription status
  3. Ensure no policies are blocking access

Azure Cosmos DB Connection Issues

Cosmos DB NoSQL

Invalid Account Name

Error: DNS resolution or connection failure

Solution:

  • Use account name only (not full URI)
  • Example: mycosmosdb not mycosmosdb.documents.azure.com

Database Name Incorrect

Error: 404 Not Found

Solution:

  • Create database in Cosmos DB Data Explorer
  • Database names are case-sensitive
  • Match exactly in Cloud Replicator Setup

Insufficient RU/s

Error: 429 Too Many Requests

Solution:

  • Increase provisioned RU/s in Azure Portal
  • Enable Autoscale for variable workloads
  • Reduce replication engine count temporarily

Cosmos DB Table API

Wrong API Type

Error: Unexpected errors during operations

Cause: Using a Core (SQL) API account instead of Table API

Solution:

  • Create new Cosmos DB account with Table API
  • Or use Cosmos DB SQL destination type for existing Core API account

Azure AI Search Connection Issues

Invalid Service Name

Error: Connection failure

Solution:

  • Use service name only, not full URL
  • Example: mysearchservice not mysearchservice.search.windows.net
  • Check service exists in Azure Portal

Wrong Key Type

Error: 403 Forbidden

Cause: Using Query key instead of Admin key

Solution:

  1. Navigate to Search service > Keys
  2. Copy an Admin key (not Query key)
  3. Admin keys are required for index management
  4. Update in Cloud Replicator Setup

Index Limit Reached

Error: Cannot create index

Solution:

  • Check index limits for your tier
  • Delete unused indexes
  • Upgrade to higher tier if needed

Testing Connections

Manual Test Steps

For each destination, test connectivity:

Azure Table Storage:

  1. Open Azure Portal
  2. Navigate to Storage Account > Tables
  3. Try creating a test table
  4. Verify access

Cosmos DB:

  1. Open Azure Portal
  2. Navigate to Cosmos DB > Data Explorer
  3. Try querying existing data
  4. Verify access

Azure AI Search:

  1. Open Azure Portal
  2. Navigate to Search service > Indexes
  3. Try Search explorer
  4. Verify access

From Business Central

Test with minimal data:

  1. Create table mapping for small table
  2. Run Manual Replication
  3. Check Replication Log
  4. Review error message if failed

Retry Configuration

Connection Retry Settings

In Cloud Replicator Setup:

Setting Default Description
Connection Retry Count 10 Number of retry attempts
Connection Retry Delay 1000 ms Delay between retries

When to Adjust

Increase Retry Count:

  • Flaky network connections
  • Services with occasional throttling
  • Higher availability requirements

Increase Retry Delay:

  • 429 errors (throttling)
  • When service needs recovery time
  • Cost optimization (reduces immediate retries)

Handling 429 Throttling

Cloud Replicator handles throttling automatically:

  1. Detects 429 response
  2. Reads Retry-After header if provided
  3. Waits specified time
  4. Retries the operation

If still seeing 429 errors:

  • Reduce parallel engine count
  • Increase delay between retries
  • Scale up cloud service capacity

Firewall and Network Configuration

Business Central Online

Business Central SaaS connects from Microsoft Azure IPs:

  • Cannot specify exact IP ranges
  • Cloud services must accept Azure connections

Firewall Options

Option 1: Allow Azure Services Most Azure services have an option to allow Azure-internal connections.

For Storage Account:

  1. Navigate to Networking
  2. Enable "Allow trusted Microsoft services"

For Cosmos DB:

  1. Navigate to Firewall and virtual networks
  2. Enable "Accept connections from within public Azure datacenters"

Option 2: Private Endpoints (Advanced) For enhanced security:

  1. Create private endpoint for Azure service
  2. Configure virtual network peering
  3. Requires additional Azure networking setup

Proxy Considerations

Business Central Online doesn't use customer proxies:

  • Direct Azure-to-Azure communication
  • Proxy settings in BC don't apply
  • Firewall rules at Azure resource level

Certificate and TLS Issues

TLS Version

Azure services require TLS 1.2 or higher:

  • Business Central Online supports TLS 1.2
  • Shouldn't be an issue in normal operation

Certificate Errors

If seeing certificate errors:

  • Usually indicates network interception
  • Contact IT to check proxy/firewall configurations
  • Azure certificates are publicly trusted

Diagnostic Steps

Step 1: Identify the Error

  1. Open Replication Log
  2. Find the failed entry
  3. Copy the exact error message

Step 2: Categorize the Error

Determine if it's:

  • Authentication (401, 403)
  • Network (Connection refused, timeout)
  • Service (404, 429, 500)

Step 3: Verify Configuration

  1. Check Setup page for correct values
  2. Compare with Azure Portal settings
  3. Re-enter credentials if uncertain

Step 4: Test Independently

  1. Access Azure Portal
  2. Verify service is operational
  3. Try operations directly in Azure

Step 5: Check Network Path

  1. Verify no known outages
  2. Check Azure status page
  3. Confirm Business Central region

Step 6: Enable Debug Mode

If issue persists:

  1. Enable Debug Mode in Setup
  2. Run small manual replication
  3. Observe detailed output
  4. Disable after testing