Skip to main content
Version: v10.x - Umbraco 10

Connection Issues

There are a wide range of ways to setup your Umbraco sites with an equally wide range of platforms and hosting solutions to choose from.

Causes of Common Issues :

When people contact us with an issue connecting two Umbraco sites with uSync.Publisher we often find it is caused by one of the following problems.

1. Load Balancing

It is not recommended to run the Umbraco backoffice environment load balanced and this is equally true of uSync.

During any push or pull operation uSync will send several requests to a server. If during that process the actual server instance changes (due to load balancing round-robbin) then the process will fail. Often with a file not found error (because files from the previous request will be missing).


If you see a 'File not found/Folder missing' error and you think your site is not load balanced, you should check. It could be load balanced in some way you are not aware of.

Operations are batched to avoid timeout issues on large site publish/syncing

2. Firewall Issues

There can be many settings on a firewall that can prevent uSync request getting through to a server:

Blocking by URL

uSync requests go to a URL starting umbraco/uSyncReceive. This is not a backoffice request URL. Blocking access to all umbraco/ requests will stop uSync.Publisher from working. You should at the very least allow requests to URLs starting with this path (from safe IP Addresses).

Blocking Request Types

During a publish or pull action uSync will send requests using the GET and POST methods. Sometimes firewalls will block POST requests and the process will fail. This usually happens at the upload step.

Blocking of Filetype Uploads

During a publish uSync.Publisher will send a number of .zip files to the target server. If your firewall or proxy is configured to filter out zip file requests then these requests might fail.

3. Host Name Issues

Sometimes a site's SSL certificate to be placed on proxy or host in front of the actual Umbraco site. Requests may go to but when they arrive at the server the SSL certificate will have been removed and requests will appear to be to

a. Use baseUrl Setting

In this situation you should set the baseURL setting for a server to be the actual address requests are sent to.

b. Disable Host Checking

If you think the issue may be related to Host names but cannot use the BaseUrl setting you can instruct uSync.Complete not to include the intended host name in the signature when checking requests.

This is theoretically slightly less secure because intercepted requests for one server could be replayed onto another, but if you are securing the route between your servers this should not be an issue.

Disable host in signature

"uSync": {
"Publisher": {
"Settings": {
"IncomingEnabled": true,
"IncludeHost": false

Turn Up The Logging

If you are unsure what is causing an issue you should turn up the logging on uSync to capture more information about what is going on.

Turn on uSync logging

Logging Tips.

1. No Logging

If after turning up the logging you see nothing being debugged on the target site, there is probably a network issue stopping the requests reaching the server.

2. Connection Mismatches

If you see mismatched signature errors in the logging then it is almost certainly a host name issue. Try either using the baseUrl or disabling the IncludeHost setting for your sites.

3. Missing Files/Folders in the Logging

If the logging is reporting missing files or folders then your issue is probably load-balancing related. You can solve this issue by:

a. Disabling load-balancing for the backoffice.

b. Turning on AAR (server affinity) in Azure to ensure all requests hit one server (This solution is not ideal).