GALsync Policies Cancel or Fail: Working Through the Causes in Order

Purpose

An export or import policy cancels, or completes with errors, while the credentials test successfully inside the policy. This is the most common class of GALsync problem and it has several unrelated causes that present almost identically. Working through them in a fixed order saves a great deal of time, because each check rules out a whole category.

Read the summary counts, not the status

Before anything else: a policy that fails to connect is cancelled and still reports a completion status. A summary reading Analyzed: 0, Added: 0, Errors: 4 means the run never got as far as looking at any objects. Finished and Completed with errors are not success.

Equally, a policy reporting adds and removes can still be failing at something else, so read the counts alongside the errors rather than either alone.

1. Check the licence is activated

Put this first because it is quick, it is invisible in the policy configuration, and an unactivated licence will cancel policies while everything else looks correctly configured. Confirm the licence is not merely installed but activated before investigating anything more complex.

2. Check the policy has an environment configuration attached

A policy with no environment configuration attached cancels with messages that point misleadingly at Exchange or at credentials:

Policy is canceled. Option: No Exchange available only AD preparation or no local
mailbox available. Transfer via email is not allowed. Please configure a Exchange
Online account for mailing

Cancelling the policy. The cancel method was called from:
GALsyncLibrary.PolicyInitiator.LogAdInformation()

The user name or password is incorrect.

The last line in particular sends people to reset service account passwords that were never wrong. If the log carries the PolicyInitiator.LogAdInformation() cancel, check whether an environment configuration is attached to that policy before touching any credentials.

3. Check the environment configuration points at the right environment

An environment configuration set to connect to Exchange on-premises when it needs to authenticate to an Exchange Online mailbox produces per-object export failures rather than an outright policy failure — large numbers of individual accounts failing with the same error code while the policy itself appears to run.

Where policies were built against an older environment model, migrating them to the current App-based environment configuration is the documented path. The manual covers this under Migrate an existing policy.

4. Check authentication method and version currency

These travel together, because Microsoft's changes to authentication are what force the version requirements.

• User-based authentication for Exchange Online has been removed as of version 8.6. Only certificate-based authentication through a registered application is supported. The option to create a new user-based credential account was removed from the environment configuration in 8.5.6.
• Version 8.7 requires .NET Framework 4.8, Windows PowerShell 5.1, and the ExchangeOnlineManagement module version 3.10.1 or later.
• Multi-factor authentication on a user account used for synchronization will block the connection. Where a user-based configuration is still in place, this is a likely cause — and the durable fix is moving to certificate-based authentication rather than excluding the account from Conditional Access.

Restrict the application's access rather than granting it broadly. The manual documents how to restrict an application's access to specific mailboxes, and a synchronization application generally needs access to one mailbox rather than the tenant.

5. Check the account context for scheduled runs

If the policy works when run manually and fails on its schedule, the cause is almost always context rather than configuration. Every scheduled policy runs as the account the GALsync Service runs as. A PowerShell module installed without -Scope AllUsers, or a certificate in your own store rather than the service account's, is present for your test and absent for the service.

Start the GALsync console logged on as the service account when you want to see what the service sees.

6. National clouds

Microsoft 365 national cloud environments — China operated by 21Vianet, and the German and US government clouds — are not the commercial cloud and need explicit configuration. Support for national cloud parameters when connecting Exchange Online mailboxes via Microsoft Graph was added in version 8.6.0. If one side of a synchronization is in a national cloud and the configuration does not account for it, expect connection behaviour that looks like intermittent failure.

Collecting the right evidence

When a case needs escalating, send from both the exporting and importing servers:

• Action → Export Configuration — policies and environment configuration.
• Action → Export Status — the log files.

Open the status archive and check the date of the newest log before sending it. An archive whose newest log predates the failing run wastes a round trip, and this happens often enough to be worth the thirty seconds. Individual runs can also be exported from the Status tab by right-clicking a run and choosing Export log file or Export all log files.

The NETsec LogViewer is the tool for reading these logs, and searching it by error code is usually faster than reading chronologically.

What not to conclude too early

Three explanations are reached for often and are frequently wrong:

• "The credentials are wrong." The credential error in the log is produced by a missing environment configuration as readily as by a bad password. Check attachment first.
• "The recipient type isn't recognised." A plausible reading of per-object export failures, but connection and environment problems produce the same pattern. Confirm the connection is healthy before adjusting the Exportable RecipientTypeDetails list.
• "A Group Policy is blocking the service account's log-on-as-a-service right." Worth checking once, but it does not explain a policy that fails identically when run manually.

In each case the cheap check that distinguishes them is the one above it in this article's order.

Related

• Troubleshooting GALsync Export Policies That Finish but Export No Data — the PowerShell module and MSAL dependency failures in detail.
• Why Objects Are Missing from a GALsync Export — when the policy runs but the data file is short.
• How to Prevent GALsync Contact Deletion During Export Errors — the export limits that stop a failed run causing deletions.

References

• GALsync 8.7 Manual p.77 — the GALsync Service; scheduled policies run in the service account's context.
• GALsync 8.7 Upgrade Instructions p.10 — .NET Framework 4.8, Windows PowerShell 5.1 and ExchangeOnlineManagement 3.10.1 requirements.
• GALsync 8.7 Manual p.233 — restricting an application's access to specific mailboxes.
• The current GALsync manual, upgrade instructions and version history are published by NETsec at netsec.de.