Skip to main content
Version: Current (v17+)

Connection Issues

There are a wide range of ways to set up 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​

If push or pull fails partway through with a 'File not found' or 'Folder missing' error, your site is probably load balanced. See the Load Balancing page for why this happens and how to fix it.

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 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.

Blocking by RequestHeaders or UserAgentString​

Some firewalls will check the RequestHeaders or UserAgentString fields in a request. If they are blank, or set to certain values, the request will be blocked. To stop this, you need to fill in the UserAgentString and RequestHeaders fields. You can use the config settings to set these values for your requests.

For example:

"UserAgentString" : "uSync agent",
"RequestHeaders": {
   "header one": "custom value one",
   "header two": "custom value two"
}

3. Hostname 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 https://www.mysite.com but when they arrive at the server the SSL certificate will have been removed and requests will appear to be to http://www.mysite.com.

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 hostnames but cannot use the BaseUrl setting you can instruct uSync.Complete not to include the intended hostname 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,
        "AppId": "XXXXXXXXXXXXX",
        "AppKey": "XXXXXXXXXXXXXX",
        "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 hostname 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 turning on Application Request Routing (ARR) on your hosting setup to ensure all requests hit one server.