Troubleshoot Azure File Sync sync health and errors

Summary

This article helps you troubleshoot and resolve common sync problems that you might encounter with your Azure File Sync deployment.

Sync health

If I create a file directly in my Azure file share over SMB or through the portal, how long does it take for the file to sync to servers in the sync group?

Changes made to the Azure file share by using the Azure portal or SMB aren't immediately detected and replicated like changes to the server endpoint. Azure Files doesn't yet have change notifications or journaling, so there's no way to automatically initiate a sync session when files change. On Windows Server, Azure File Sync uses Windows USN journaling to automatically initiate a sync session when files change.

To detect changes to the Azure file share, Azure File Sync has a scheduled job called a change detection job. A change detection job enumerates every file in the file share, and then compares it to the sync version for that file. When the change detection job determines that files changed, Azure File Sync initiates a sync session. The change detection job runs every 24 hours. Because the change detection job works by enumerating every file in the Azure file share, change detection takes longer in larger namespaces than in smaller namespaces. For large namespaces, it might take longer than 24 hours to determine which files changed.

To immediately sync files that you change in the Azure file share, use the Invoke-AzStorageSyncChangeDetection PowerShell cmdlet to manually initiate the detection of changes in the Azure file share. This cmdlet is intended for scenarios where some type of automated process is making changes in the Azure file share or an administrator makes the changes (like moving files and directories into the share). For end user changes, install the Azure File Sync agent in an IaaS VM and have end users access the file share through the IaaS VM. This way all changes quickly sync to other agents without the need to use the Invoke-AzStorageSyncChangeDetection cmdlet. To learn more, see the Invoke-AzStorageSyncChangeDetection documentation.

Microsoft is exploring adding change detection for an Azure file share similar to USN for volumes on Windows Server. Help prioritize this feature for future development by voting for it at Azure Community Feedback.

Server endpoint health is in a pending state for several hours

This state is expected if you create a cloud endpoint and use an Azure file share that contains data. The cloud change enumeration job that scans for changes in the Azure file share must complete before files can sync between the cloud and server endpoints. The time to complete the job depends on the size of the namespace in the Azure file share. The server endpoint health updates once the change enumeration job completes.

To check the status of the cloud change enumeration job, go the Cloud Endpoint properties in the portal. The Change Enumeration section provides the status.

How do I monitor sync health?

Replica Sync session completed.
SyncDirection: Upload,
HResult: 0, 
SyncFileCount: 2, SyncDirectoryCount: 0,
AppliedFileCount: 2, AppliedDirCount: 0, AppliedTombstoneCount 0, AppliedSizeBytes: 0.
PerItemErrorCount: 0,
TransferredFiles: 2, TransferredBytes: 0, FailedToTransferFiles: 0, FailedToTransferBytes: 0.

Replica Sync session completed.
SyncDirection: Upload,
HResult: -2134364065,
SyncFileCount: 0, SyncDirectoryCount: 0, 
AppliedFileCount: 0, AppliedDirCount: 0, AppliedTombstoneCount 0, AppliedSizeBytes: 0.
PerItemErrorCount: 0, 
TransferredFiles: 0, TransferredBytes: 0, FailedToTransferFiles: 0, FailedToTransferBytes: 0.

How do I monitor the progress of a current sync session?

Replica Sync Progress. 
ServerEndpointName: <CI>sename</CI>, SyncGroupName: <CI>sgname</CI>, ReplicaName: <CI>rname</CI>, 
SyncDirection: Upload, CorrelationId: {aaaa0000-bb11-2222-33cc-444444dddddd}. 
AppliedItemCount: 172473, TotalItemCount: 624196. AppliedBytes: 51473711577, 
TotalBytes: 293363829906. 
AreTotalCountsFinal: true. 
PerItemErrorCount: 1006.

How do I know if my servers are in sync with each other?

How do I see if there are specific files or folders that aren't syncing?

If the Persistent sync errors and Transient sync errors counts in the portal or PerItemErrorCount on the server is greater than 0 for any given sync session, that means some items are failing to sync. Files and folders can have characteristics that prevent them from syncing. These characteristics can be persistent and require explicit action to resume sync, for example removing unsupported characters from the file or folder name. They can also be transient, meaning the file or folder will automatically resume sync; for example, files with open handles will automatically resume sync when the file is closed. When the Azure File Sync engine detects such a problem, an error log is produced that can be parsed to list the items currently not syncing properly.

To see the names of files and directories that are failing to sync, run the FileSyncErrorsReport.ps1 PowerShell script (located in the agent installation directory of the Azure File Sync agent) or use the Debug-StorageSyncServer cmdlet. The ItemPath field tells you the location of the file in relation to the root sync directory. See the list of common per-item errors for remediation steps.

To identify files that fail to sync on the server by using the Debug-StorageSyncServer cmdlet, run the following PowerShell commands:

Import-Module "C:\Program Files\Azure\StorageSyncAgent\StorageSync.Management.ServerCmdlets.dll"
Debug-StorageSyncServer -FileSyncErrorsReport

Sync errors

Troubleshooting per file/directory sync errors

If a file or directory fails to sync due to an error, an event is logged in the Microsoft-FileSync-Agent/ItemResults event log. This section covers common error codes and remediation steps for per-item errors.

Find the hexadecimal HRESULT, decimal HRESULT, or error string from the ItemResults event log in the following list. Each entry describes the issue and its resolution.

ERROR_BAD_NET_NAME: The tiered file on the server isn't accessible.

See Tiered files are not accessible on the server.

ECS_E_SYNC_CONSTRAINT_CONFLICT: The file or directory change can't be synced yet because a dependent folder isn't yet synced.

This error is transient. If it persists for several days, create a support request.

ECS_E_SYNC_CONSTRAINT_CONFLICT_ON_FAILED_DEPENDEE: The file or directory change can't be synced yet because a dependent folder isn't yet synced.

This error is transient. If it persists, use the FileSyncErrorsReport.ps1 PowerShell script to determine why the dependent folder isn't yet synced.

ECS_E_SYNC_ITEM_PROCESS_FAIL_RECOVERABLE: The file or directory change can't be synced yet because the item encountered a recoverable failure.

This error is transient. If it persists for several days, create a support request.

ECS_E_SYNC_CONSTRAINT_CONFLICT_SESSION_FAILED: The file or directory change can't be synced yet because a dependent folder isn't yet synced and the sync session failed.

No action is required. If the error persists, investigate the sync session failure.

ERROR_INVALID_NAME: The file or directory name is invalid.

Rename the file or directory. For more information, see Handling unsupported characters.

ERROR_NO_UNICODE_TRANSLATION: The file or directory name has unsupported surrogate pair characters.

Rename the file or directory. For more information, see Handling unsupported characters.

ECS_E_XSMB_REST_INCOMPATIBILITY: The file or directory name is invalid.

Rename the file or directory. For more information, see Handling unsupported characters.

ECS_E_SYNC_ITEM_RESTRICTED_AT_ROOT: The specified item name is restricted at the root of the sync share and can't be synchronized.

No action is required. For more information, see File system compatibility.

ECS_E_SYNC_FILE_IN_USE: The file can't be synced because it's in use.

No action is required. Azure File Sync creates a temporary Volume Shadow Copy Service (VSS) snapshot once a day on the server to sync files that have open handles.

ECS_E_SYNC_CLOUD_FILE_IN_USE: The cloud file can't be synced because an application holds an open handle to it.

Check for open file handles and close them if they're no longer needed by using the Get-AzStorageFileHandle and Close-AzStorageFileHandle PowerShell cmdlets.

ECS_E_CONCURRENCY_CHECK_FAILED: The file changed, but sync hasn't detected the change yet.

No action is required.

ECS_E_AZURE_FILE_PATH_TOO_LONG: The file path is longer than the supported Azure Files path length.

Run the FileSyncErrorsReport.ps1 PowerShell script in the Azure File Sync agent installation directory to identify failing file paths. Then, use the ScanUnsupportedChars script.

ERROR_FILE_NOT_FOUND: The file was deleted, but sync isn't aware of the change.

No action is required. Sync stops logging this error after change detection detects that the file was deleted.

ERROR_PATH_NOT_FOUND: A file or directory deletion can't be synced because the item was already deleted at the destination, but sync isn't aware of the change.

No action is required. Sync stops logging this error after change detection runs on the destination and detects that the item was deleted.

ECS_E_SYNC_ITEM_SKIP: The file or directory was skipped but will be synced during the next sync session.

No action is required if the error occurs during upload. If the error occurs during download, rename the file or directory. For more information, see Handling unsupported characters.

ERROR_ALREADY_EXISTS: A file or directory can't be created because the item already exists at the destination, but sync isn't aware of it.

No action is required. Sync stops logging this error after change detection runs on the destination and detects the item.

ECS_E_AZURE_STORAGE_SHARE_SIZE_LIMIT_REACHED: The file can't be synced because the Azure file share limit is reached.

See You reached the Azure file share storage limit.

ECS_E_CANNOT_CREATE_AZURE_STAGED_FILE: The file can't be synced because the Azure file share limit is reached.

See You reached the Azure file share storage limit.

ECS_E_ACCESS_DENIED_EFS: The file is encrypted by an unsupported solution, such as NTFS Encrypting File System (EFS).

Decrypt the file and use a supported encryption solution. For more information, see Encryption.

ECS_E_ACCESS_DENIED_DFSRRO: The file is in a Distributed File System Replication (DFS-R) read-only replication folder.

Azure File Sync doesn't support server endpoints on DFS-R read-only replication folders. For more information, see Distributed File System (DFS).

ERROR_ACCESS_DENIED: The file has a pending deletion.

No action is required. The file is deleted after all open file handles are closed.

ECS_E_AZURE_AUTHORIZATION_FAILED: The file can't be synced because the storage account firewall and virtual network settings are enabled, and the server doesn't have access to the storage account.

Add the server IP address or virtual network. For more information, see Configure firewall and virtual network settings.

E_UNEXPECTED: The file can't be synced because of an unexpected error.

If the error persists for several days, create a support request.

ECS_E_ETAG_VERIFCATION_FAILED: The file can't be synced because ETag verification with the target failed.

If the error persists for several days, create a support request.

ERROR_SHARING_VIOLATION: The file can't be synced because it's in use.

No action is required.

ECS_E_SYNC_OPLOCK_BROKEN: The file changed during sync and must be synced again.

No action is required.

ERROR_CRC: The file can't be synced because of a cyclic redundancy check (CRC) error.

See Tiered files are not accessible on the server to remove orphaned tiered files. If the error continues after you remove orphaned tiered files, run chkdsk on the volume.

ERROR_FILE_INVALID: The file can't be synced because it's no longer valid.

If the file is tiered, see Tiered files are not accessible on the server to remove orphaned tiered files.

ERROR_FILE_CORRUPT: The file or directory is corrupted and unreadable.

Run chkdsk on the volume.

ECS_E_SYNC_CONFLICT_NAME_EXISTS: The file can't be synced because the maximum number of conflict files was reached.

Reduce the number of conflict files. The file syncs after the number of conflict files is less than 100. For more information, see Azure File Sync FAQ.

ECS_E_DIRECTORY_RENAME_FAILED: A directory can't be renamed because files or folders in the directory have open handles.

No action is required. The directory is renamed after all open file handles in the directory are closed.

ERROR_BAD_FILE_TYPE: The tiered file on the server isn't accessible because it references a version of the file that no longer exists in the Azure file share.

This issue can occur if the tiered file was restored from a Windows Server backup. Restore the file from an Azure file share snapshot.

ECS_E_DATA_TRANSFER_BLOCKED: The file caused persistent sync errors and is blocked from sync until the retry interval is reached.

No action is required. The file is retried after 24 hours. If the error persists for several days, create a support request.

ECS_E_SYNC_INVALID_STAGED_FILE: A file transfer error occurred.

No action is required. This error should resolve automatically. If it persists for several days, create a support request.

ECS_E_SYNC_CONSTRAINT_CONFLICT_CYCLIC_DEPENDENCY: The sync session timed out.

No action is required. This error should resolve automatically. If it persists for several days, create a support request.

ERROR_BAD_NETPATH: The network path wasn't found.

No action is required. This error should resolve automatically. If it persists for several days, create a support request.

ERROR_FILE_READ_ONLY: The specified file is read-only.

If the error persists for more than a day, create a support request.

ERROR_INVALID_HANDLE: An internal error occurred.

If the error persists for more than a day, create a support request.

ERROR_NOT_SUPPORTED: The tiered file is likely orphaned and can't be uploaded.

No remediation is currently documented for this error.

ERROR_DELETE_PENDING: The file can't be opened because it's being deleted.

This error should resolve automatically. If it doesn't, check for open file handles and close them if they're no longer needed by using the Get-AzStorageFileHandle and Close-AzStorageFileHandle PowerShell cmdlets.

SYNC_E_ITEM_MUST_EXIST: An internal error occurred.

If the error persists for more than a day, create a support request.

ECS_E_SYNC_INITIAL_SCAN_COMPLETED: The sync session failed because the initial enumeration completed.

No action is required. This error should resolve automatically. If it persists for several days, create a support request.

ECS_E_SYNC_CUSTOM_METADATA_VERSION_NOT_SUPPORTED: The sync database has custom metadata with a version that's higher than the supported version.

Upgrade the Azure File Sync agent to the latest version. If the error persists after the upgrade, create a support request.

ECS_E_AZURE_FILE_SHARE_FILE_NOT_FOUND: The specified Azure file wasn't found in the file share.

No action is required. Sync stops logging this error after change detection detects that the file was deleted.

ECS_E_SYNC_UNPROCESSABLE_ITEM_REPARSEPOINT: The item can't be synced because it contains a reparse point.

Remove the reparse point or replace it with regular file content, and then try syncing again.

ECS_E_ITEM_PATH_COMPONENT_HAS_TRAILING_DOT: The item can't be synced because one of its path components has trailing periods.

Rename the item by removing trailing periods from the path.

ECS_E_SYNC_ITEM_SKIP_CONSTRAINT_CONFLICT_NOT_ALLOWED: A constraint conflict was detected but couldn't be reported, so the item is skipped.

If the error persists, create a support request.

ECS_E_SYNC_ITEM_RECONCILIATION_SKIP: A file or directory was skipped while sync rebuilt the sync client metadata.

If the error persists for several days, create a support request.

Handling unsupported characters

Azure File Sync agent v17 supports all characters that are supported by the NTFS file system except invalid surrogate pairs.

If the portal or FileSyncErrorsReport.ps1 PowerShell script shows per-item sync errors (error code 0x8007007b, 0x80c80255, or 0x80070459) due to unsupported characters, check whether Azure File Sync agent v17 is installed on the server. If agent v17 is installed and files still fail to sync due to invalid characters, use the ScanUnsupportedChars script to rename files that contain unsupported characters.

Common sync errors

This section covers common error codes and remediation steps when a sync session fails with an error.

ERROR_CANCELLED: The sync session was canceled.

Sync sessions might fail for various reasons including the server being restarted or updated, VSS snapshots, etc. Although this error looks like it requires follow-up, it's safe to ignore this error unless it persists over a period of several hours.

ECS_E_SYNC_CANCELLED_BY_VSS: The file sync session was cancelled by the volume snapshot sync session that runs once a day to sync files with open handles.

No action required. Azure File Sync has a scheduled task (VssSyncScheduledTask) that runs once a day on the server to sync files that are in use. When this scheduled task starts, it will cancel the current upload sync session (resulting in the 0x80c8029c error code), create a VSS snapshot, and start a new upload sync session utilizing the VSS snapshot.

WININET_E_NAME_NOT_RESOLVED and related errors: A connection with the service couldn't be established.

This error can occur whenever the Azure File Sync service is inaccessible from the server. You can troubleshoot this error by working through the following steps:

1. Verify the Windows service FileSyncSvc.exe isn't blocked by your firewall.

2. Verify that port 443 is open to outgoing connections to the Azure File Sync service. You can do this with the Test-NetConnection cmdlet. The URL for the <azure-file-sync-endpoint> placeholder below can be found in the Azure File Sync proxy and firewall settings document.

   Test-NetConnection -ComputerName <azure-file-sync-endpoint> -Port 443
   

3. Ensure that the proxy configuration is set as anticipated. This can be done with the Get-StorageSyncProxyConfiguration cmdlet. More information on configuring the proxy configuration for Azure File Sync can be found in the Azure File Sync proxy and firewall settings.

   $agentPath = "C:\Program Files\Azure\StorageSyncAgent"
   Import-Module "$agentPath\StorageSync.Management.ServerCmdlets.dll"
   Get-StorageSyncProxyConfiguration
   

4. Use the Test-StorageSyncNetworkConnectivity cmdlet to check network connectivity to the service endpoints. To learn more, see Test network connectivity to service endpoints.

5. Contact your network administrator for additional assistance troubleshooting network connectivity.

ECS_E_USER_REQUEST_THROTTLED: The user request was throttled by the service.

No action is required; the server will try again. If this error persists for several hours, create a support request.

ECS_E_OPERATION_ABORTED: Sync failed because the operation was aborted

No action is required. If this error persists for several hours, create a support request.

ECS_E_REQUEST_CANCELLED_EXTERNALLY and related errors: The operation was cancelled.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_SYNC_BLOCKED_ON_CHANGE_DETECTION_POST_RESTORE: Sync is blocked until change detection completes post restore

No action is required. When a file or file share (cloud endpoint) is restored using Azure Backup, sync is blocked until change detection completes on the Azure file share. Change detection immediately runs once the restore is complete and the duration is based on the number of files in the file share.

ECS_E_SYNC_BLOCKED_ON_RESTORE: Sync is blocked on the folder due to a pause initiated as part of restore on sync folder.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

SYNC_E_METADATA_INVALID_OPERATION: Sync failed because the sync database was unloaded.

This error typically happens when a backup application creates a VSS snapshot and the sync database is unloaded. If this error persists for several hours, create a support request.

ECS_E_EXTERNAL_STORAGE_ACCOUNT_AUTHORIZATION_FAILED and related errors: Sync can't access the Azure file share specified in the cloud endpoint.

This error occurs because the Azure File Sync agent can't access the Azure file share, which might be because the Azure file share or the storage account hosting it no longer exists. You can troubleshoot this error by working through the following steps:

1. Verify the storage account exists.
2. Ensure the Azure file share exists.
3. Ensure Azure File Sync has access to the storage account.
4. Verify the SMB security settings on the storage account are allowing SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.
5. Verify the firewall and virtual network settings on the storage account are configured properly (if enabled)

ECS_E_AZURE_AUTHORIZATION_FAILED: Sync failed because the request isn't authorized to perform this operation.

This error occurs because the Azure File Sync agent isn't authorized to access the Azure file share. You can troubleshoot this error by working through the following steps:

1. Verify the storage account exists.
2. Ensure the Azure file share exists.
3. Verify the firewall and virtual network settings on the storage account are configured properly (if enabled)
4. Ensure Azure File Sync has access to the storage account.

ECS_E_STORAGE_ACCOUNT_NAME_UNRESOLVED: The storage account name used couldn't be resolved.

1. Check that you can resolve the storage DNS name from the server.

   Test-NetConnection -ComputerName <storage-account-name>.file.core.windows.net -Port 443
   

2. Verify the storage account exists.

3. Verify the firewall and virtual network settings on the storage account are configured properly (if enabled)

ECS_E_STORAGE_ACCOUNT_UNKNOWN_ERROR: An unknown error occurred while accessing the storage account.

1. Verify the storage account exists.
2. Verify the firewall and virtual network settings on the storage account are configured properly (if enabled)

ECS_E_STORAGE_ACCOUNT_LOCKED: Sync failed due to storage account locked.

This error occurs because the storage account has a read-only resource lock. To resolve this issue, remove the read-only resource lock on the storage account.

JET_errWriteConflict: Sync failed due to a problem with the sync database.

This error happens when there's a problem with the internal database used by Azure File Sync. When this issue occurs, create a support request and we will contact you to help you resolve this issue.

ECS_E_AGENT_VERSION_BLOCKED: The Azure File Sync agent version installed on the server isn't supported.

This error occurs if the Azure File Sync agent version installed on the server isn't supported. To resolve this issue, upgrade to a supported agent version.

ECS_E_AZURE_STORAGE_SHARE_SIZE_LIMIT_REACHED and related errors: You reached the Azure file share storage limit.

Sync sessions fail with either of these errors when the Azure file share storage limit has been reached, which can happen if a quota is applied for an Azure file share or if the usage exceeds the limits for an Azure file share. For more information, see the current limits for an Azure file share.

1. Navigate to the sync group within the Storage Sync Service.

2. Select the cloud endpoint within the sync group.

3. Note the Azure file share name in the opened pane. Select the file share name to open the file share settings page in the storage account.

   

4. Select the file share to get the details on the Overview page.

5. Select Edit quota to verify the file share quota. Unless an alternate quota has been specified, the quota will match the maximum size of the Azure file share.

   

If the file share is full (the used capacity equals the quota), free up space on the file share. One possible way of fixing this issue is to make each subfolder of the current server endpoint into its own server endpoint in their own separate sync groups. This way each subfolder will sync to individual Azure file shares.

ECS_E_AZURE_FILE_SHARE_NOT_FOUND: The Azure file share can't be found.

This error happens when the Azure file share isn't accessible. To troubleshoot:

1. Verify the storage account exists.
2. Ensure the Azure file share exists.
3. Verify the SMB security settings on the storage account are allowing SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.

If the Azure file share was deleted, you need to create a new file share and then recreate the sync group.

ECS_E_SYNC_BLOCKED_ON_SUSPENDED_SUBSCRIPTION: Sync is paused while this Azure subscription is suspended.

This error happens when the Azure subscription is suspended. Sync is reenabled when the Azure subscription is restored. See Why is my Azure subscription disabled and how do I reactivate it? for more information.

ECS_E_SERVER_BLOCKED_BY_NETWORK_ACL: The storage account has a firewall or virtual networks configured.

This error happens when the Azure file share is inaccessible because of a storage account firewall or because the storage account belongs to a virtual network. Verify the firewall and virtual network settings on the storage account are configured properly. For more information, see Configure firewall and virtual network settings.

ECS_E_SYNC_METADATA_WRITE_LOCK_TIMEOUT and related errors: Sync failed due to a problem with the sync database.

These errors usually resolve themselves and can occur if there are:

• A high number of file changes across the servers in the sync group.
• A large number of errors on individual files and directories.

If this error persists for longer than a few hours, create a support request and we will contact you to help you resolve this issue.

ECS_E_SYNC_METADATA_IO_BUSY: The sync database has encountered a storage busy IO error.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_SYNC_METADATA_IO_TIMEOUT: The sync database has encountered an IO timeout.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_SYNC_METADATA_IO_ERROR: The sync database has encountered an IO error.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ERROR_INVALID_REPARSE_DATA: Sync failed because the data is corrupted and unreadable.

This error can occur if there's a file system corruption on the NTFS volume where the server endpoint is located. To resolve this error, run chkdsk on the volume.

ERROR_REPARSE_TAG_INVALID: Sync failed because the tag present in the reparse point buffer is invalid.

This error happens when files are copied between servers with different configurations. For example, transferring files from a server with a file system filter driver or deduplication feature enabled to one where these features aren't present can result in unreadable files due to invalid reparse points. To resolve this error, delete the affected files or recopy them as actual files rather than reparse points.

CERT_E_UNTRUSTEDROOT: The server failed to establish a secure connection. The cloud service received an unexpected certificate.

This error can happen if your organization is using a TLS terminating proxy or if a malicious entity is intercepting the traffic between your server and the Azure File Sync service. If you're certain that this is expected (because your organization is using a TLS terminating proxy), you skip certificate verification with a registry override.

1. Create the SkipVerifyingPinnedRootCertificate registry value.

   New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Azure\StorageSync -Name SkipVerifyingPinnedRootCertificate -PropertyType DWORD -Value 1
   

2. Restart the sync service on the registered server.

   Restart-Service -Name FileSyncSvc -Force
   

When you set this registry value, the Azure File Sync agent accepts any locally trusted TLS/SSL certificate when it transfers data between the server and the cloud service.

WININET_E_DECODING_FAILED: Sync failed because the server was unable to decode the response from the Azure File Sync service.

This error typically occurs if a firewall, proxy, or gateway blocks access to the PKI URL, or if the PKI server is down.

To resolve this issue, ensure that the server can access the following URLs:

• https://www.microsoft.com/pki/mscorp/cps
• http://crl.microsoft.com/pki/mscorp/crl/
• http://mscrl.microsoft.com/pki/mscorp/crl/
• http://ocsp.msocsp.com
• http://ocsp.digicert.com/
• http://crl3.digicert.com/

Once the Azure File Sync agent is installed, the PKI URL is used to download the intermediate certificates required to communicate with the Azure File Sync service and Azure file share. The OCSP URL is used to check the status of a certificate. If the error persists for several days, create a support request.

ECS_E_SERVER_CREDENTIAL_NEEDED: Sync failed due to a problem with authentication.

This error typically occurs because the server time is incorrect. If the server is running in a virtual machine, verify the time on the host is correct.

ECS_E_AUTH_SRV_CERT_EXPIRED: Sync failed due to certificate expiration.

This error occurs because the certificate used for authentication is expired.

To confirm the certificate is expired, perform the following steps:

1. Open the Certificates MMC snap-in, select Computer Account and navigate to Certificates (Local Computer)\Personal\Certificates.
2. Check if the client authentication certificate is expired.

If the client authentication certificate is expired, run the following PowerShell command on the server:

Reset-AzStorageSyncServerCertificate -ResourceGroupName <string> -StorageSyncServiceName <string>

ECS_E_AUTH_SRV_CERT_NOT_FOUND: Sync failed due to authentication certificate not found.

This error occurs because the certificate used for authentication isn't found.

To resolve this issue, run the following PowerShell command on the server:

Reset-AzStorageSyncServerCertificate -ResourceGroupName <string> -StorageSyncServiceName <string>

ECS_E_AUTH_IDENTITY_NOT_FOUND: Sync failed due to authentication identity not found.

This error might occur due to the following reasons:

• The server's managed identity tenant ID doesn't match the tenant ID of the Storage Sync Service or the storage account.
• The server was recently re-registered or its managed identity configuration changed, but the update hasn't propagated yet.

JET_errLogDiskFull and related errors: The volume where the server endpoint is located is low on disk space.

Sync sessions fail with one of these errors because the volume has insufficient disk space or has reached its disk quota. This error commonly occurs because files outside the server endpoint are using up space on the volume. Check the available disk space on the server. You can free up space on the volume by adding additional server endpoints, moving files to a different volume, or increasing the size of the volume the server endpoint is on. If you configured a disk quota on the volume by using File Server Resource Manager or NTFS quota, increase the quota limit.

If cloud tiering is enabled for the server endpoint, verify the files are syncing to the Azure file share to avoid running out of disk space.

ECS_E_REPLICA_NOT_READY: The service isn't yet ready to sync with this server endpoint.

This error happens when you create a cloud endpoint that uses an Azure file share with existing content. Azure File Sync must scan all content in the file share before the server endpoint can begin its initial synchronization. After change detection completes, sync starts. Change detection can take longer than 24 hours and is proportional to the number of files and directories in your Azure file share. If you configured cloud tiering, Azure File Sync tiers files after sync completes.

ECS_E_SYNC_METADATA_KNOWLEDGE_SOFT_LIMIT_REACHED and related errors: Sync failed due to problems with many individual files.

Sync sessions fail with one of these errors when there are many files that are failing to sync with per-item errors. Perform the steps documented in the How do I see if there are specific files or folders that aren't syncing? section to resolve the per-item errors. For sync error ECS_E_SYNC_METADATA_KNOWLEDGE_LIMIT_REACHED, please open a support case.

ECS_E_SYNC_INVALID_PATH: Sync failed due to a problem with the server endpoint path.

Ensure the path exists, is on a local NTFS volume, and isn't a reparse point or existing server endpoint.

ECS_E_INCOMPATIBLE_FILTER_VERSION: Sync failed because the filter driver version isn't compatible with the agent version

This error occurs because the Cloud Tiering filter driver (StorageSync.sys) version loaded isn't compatible with the Storage Sync Agent (FileSyncSvc) service. If the Azure File Sync agent was upgraded, restart the server to complete the installation. If the error continues to occur, uninstall the agent, restart the server and reinstall the Azure File Sync agent.

ECS_E_SERVICE_UNAVAILABLE: The service is currently unavailable.

This error occurs because the Azure File Sync service is unavailable. This error will auto-resolve when the Azure File Sync service is available again.

COR_E_EXCEPTION: Sync failed due to an exception.

This error occurs because sync failed due to an exception. If the error persists for several hours, please create a support request.

ECS_E_STORAGE_ACCOUNT_FAILED_OVER: Sync failed because the storage account has failed over to another region.

This error occurs because the storage account has failed over to another region. Azure File Sync doesn't support the storage account failover feature. Storage accounts containing Azure file shares being used as cloud endpoints in Azure File Sync shouldn't be failed over. Doing so causes sync to stop working and might also cause unexpected data loss in the case of newly tiered files. To resolve this issue, move the storage account to the primary region.

ECS_E_SYNC_METADATA_WRITE_LEASE_LOST: Sync failed due to a transient problem with the sync database.

This error occurs because of an internal problem with the sync database. This error will auto-resolve when sync retries. If this error continues for an extend period of time, create a support request, and we will contact you to help you resolve this issue.

ECS_E_INVALID_AAD_TENANT: Sync failed due to change in Microsoft Entra tenant

Verify you have the latest Azure File Sync agent version installed and give the Microsoft.StorageSync application access to the storage account (see Ensure Azure File Sync has access to the storage account).

ECS_E_MGMT_STORAGEACLSBYPASSNOTSET: Sync failed due to firewall and virtual network exception not configured

This error occurs if the firewall and virtual network settings are enabled on the storage account and the "Allow trusted Microsoft services to access this storage account" exception isn't checked. To resolve this issue, follow the steps documented in the Configure firewall and virtual network settings section in the deployment guide.

ERROR_ACCESS_DENIED: Sync failed with access denied due to security settings on the storage account or NTFS permissions on the server.

This error can occur if Azure File Sync can't access the storage account due to security settings or if the NT AUTHORITY\SYSTEM account doesn't have permissions to the System Volume Information folder on the volume where the server endpoint is located. If individual files are failing to sync with ERROR_ACCESS_DENIED, perform the steps documented in the Troubleshooting per file/directory sync errors section.

1. Verify the SMB security settings on the storage account are allowing SMB 3.1.1 protocol version, NTLM v2 authentication and AES-128-GCM encryption. To check the SMB security settings on the storage account, see SMB security settings.

2. Verify the firewall and virtual network settings on the storage account are configured properly (if enabled)

3. Verify the NT AUTHORITY\SYSTEM account has permissions to the System Volume Information folder on the volume where the server endpoint is located by performing the following steps:

   1. Download Psexec tool.

   2. Run the following command from an elevated command prompt to launch a command prompt using the system account: PsExec.exe -i -s -d cmd.

   3. From the command prompt running under the system account, run the following command to confirm the NT AUTHORITY\SYSTEM account doesn't have access to the System Volume Information folder: cacls "drive letter:\system volume information" /T /C.

   4. If the NT AUTHORITY\SYSTEM account doesn't have access to the System Volume Information folder, run the following command: cacls "drive letter:\system volume information" /T /E /G "NT AUTHORITY\SYSTEM:F".

      If step d fails with access denied, run the following command to take ownership of the System Volume Information folder and then repeat step d:

      takeown /A /R /F "drive letter:\System Volume Information"

ECS_E_SYNC_REPLICA_ROOT_CHANGED: Sync failed because the Azure file share was deleted and recreated.

This error occurs because Azure File Sync doesn't support deleting and recreating an Azure file share in the same sync group.

To resolve this issue, delete and recreate the sync group by performing the following steps:

1. Delete all server endpoints in the sync group.
2. Delete the cloud endpoint.
3. Delete the sync group.
4. If cloud tiering was enabled on a server endpoint, delete the orphaned tiered files on the server by performing the steps documented in the Tiered files are not accessible on the server section.
5. Recreate the sync group.

ECS_E_SYNC_REPLICA_BACK_IN_TIME: Sync detected the replica has been restored to an older state

No action is required. This error occurs because sync detected the replica has been restored to an older state. Sync will now enter a reconciliation mode, where it recreates the sync relationship by merging the contents of the Azure file share and the data on the server endpoint. When reconciliation mode is triggered, the process can be very time consuming, depending upon the namespace size. Regular synchronization doesn't happen until the reconciliation finishes, and files that are different (last modified time or size) between the Azure file share and server endpoint will result in file conflicts.

ECS_E_SYNC_ROOT_VOLUME_CHANGED: Sync failed because the path for the server endpoint has changed

This error occurs because the path where the server endpoint is provisioned is now on a different volume than it was originally provisioned. When this issue occurs, create a support request and we will contact you to help you resolve it.

HTTP_E_STATUS_REDIRECT_KEEP_VERB: Sync failed because the HTTP request was redirected

This error occurs because Azure File Sync doesn't support HTTP redirection (3xx status code). To resolve this issue, disable HTTP redirect on your proxy server or network device.

ECS_E_WORK_FRAMEWORK_TIMEOUT and related errors: Sync session timeout error.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

COR_E_TIMEOUT: Operation time out.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_AZURE_OPERATION_TIME_OUT: Time out error.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_SYNC_ROOT_DIRECTORY_NOT_FOUND: Sync failed because the server endpoint path can't be found on the server.

This error occurs if the directory used as the server endpoint path was renamed or deleted. If the directory was renamed, rename the directory back to the original name and restart the Storage Sync Agent service (FileSyncSvc).

If the directory was deleted, perform the following steps to remove the existing server endpoint and create a new server endpoint using a new path:

1. Remove the server endpoint in the sync group by following the steps documented in Remove a server endpoint.
2. Create a new server endpoint in the sync group by following the steps documented in Add a server endpoint.

ECS_E_SYNC_AUTHORITATIVE_UPLOAD_EMPTY_SET: Server endpoint provisioning failed due to an empty server path.

Server endpoint provisioning fails with this error code if these conditions are met:

• This server endpoint was provisioned with the initial sync mode: server authoritative
• Local server path is empty or contains no items recognized as able to sync.

This provisioning error protects you from deleting all content that might be available in an Azure file share. Server authoritative upload is a special mode to catch up a cloud location that was already seeded, with the updates from the server location. Review this migration guide to understand the scenario for which this mode has been built.

1. Remove the server endpoint in the sync group by following the steps documented in Remove a server endpoint.
2. Create a new server endpoint in the sync group by following the steps documented in Add a server endpoint.

ECS_E_STORAGE_ACCOUNT_SUBSCRIPTION_DISABLED: The subscription owning the storage account is disabled.

Make sure the subscription that contains your storage account is enabled.

ERROR_NETNAME_DELETED: The specified network name is no longer available.

Use the Test-StorageSyncNetworkConnectivity cmdlet to check network connectivity to the service endpoints. For more information, see Test network connectivity to service endpoints.

ECS_E_CANNOT_CREATE_ACTIVE_SESSION_PLACEHOLDER_BLOB and related errors: Sync session error.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_TOO_MANY_ETAGVERIFICATION_FAILURES and related errors: Sync session error.

If the error persists for more than a day, create a support request.

ERROR_INVALID_PARAMETER and related errors: An internal error occurred.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

COR_E_INVALIDOPERATION and related errors: An internal error occurred.

If the error persists for more than a day, create a support request.

E_POINTER: An internal error occurred.

Please upgrade to the latest file sync agent version. If the error persists after upgrading the agent, create a support request.

ERROR_LOGON_FAILURE and related errors: Operation failed due to an authentication failure.

If the error persists for more than a day, create a support request.

ECS_E_AZURE_ACCOUNT_IS_DISABLED: The specified Azure account is disabled.

Make sure the subscription that contains your storage account is enabled.

ECS_E_STORAGE_ACCOUNT_KEY_BASED_AUTHENTICATION_BLOCKED: Storage account key based authentication blocked.

Enable "Allow storage account key access" on the storage account. Learn more.

ECS_E_SYNC_EPOCH_MISMATCH: Sync needs to update the database on the server.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ECS_E_VOLUME_OFFLINE: The volume is offline. It might be removed, not ready, or disconnected.

Please verify the volume where the server endpoint is located is attached to the server.

ECS_E_PRIVATE_ENDPOINT_ACCESS_BLOCKED: Private endpoint configuration access blocked.

Check the private endpoint configuration and allow access to the file sync service. Learn more.

ECS_E_REPLICA_RECONCILIATION_NEEDED: Sync needs to reconcile the server and Azure file share data before files can be uploaded.

No action required. This error should automatically resolve. If the error persists for several days, create a support request.

ERROR_SESSION_CREDENTIAL_CONFLICT: Multiple connections to a server or shared resource by the same user, using more than one user name, aren't allowed.

Disconnect all previous connections to the server or shared resource and try again.

ECS_E_SERVER_INVALID_OR_EXPIRED_CERTIFICATE: The server's SSL certificate is invalid or expired.

Run the following PowerShell command on the server to reset the certificate:

Reset-AzStorageSyncServerCertificate -ResourceGroupName <string> -StorageSyncServiceName <string>

Common troubleshooting steps

Verify the storage account exists.

# Variables for you to populate based on your configuration
$region = "<Az_Region>"
$resourceGroup = "<RG_Name>"
$syncService = "<storage-sync-service>"
$syncGroup = "<sync-group>"

# Log into the Azure account
Connect-AzAccount

# Check to ensure Azure File Sync is available in the selected Azure
# region.
$regions = [System.String[]]@()
Get-AzLocation | ForEach-Object { 
    if ($_.Providers -contains "Microsoft.StorageSync") { 
        $regions += $_.Location 
    } 
}

if ($regions -notcontains $region) {
    throw [System.Exception]::new("Azure File Sync is either not available in the " + `
        " selected Azure Region or the region is mistyped.")
}

# Check to ensure resource group exists
$resourceGroups = [System.String[]]@()
Get-AzResourceGroup | ForEach-Object { 
    $resourceGroups += $_.ResourceGroupName 
}

if ($resourceGroups -notcontains $resourceGroup) {
    throw [System.Exception]::new("The provided resource group $resourceGroup does not exist.")
}

# Check to make sure the provided Storage Sync Service
# exists.
$syncServices = [System.String[]]@()

Get-AzStorageSyncService -ResourceGroupName $resourceGroup | ForEach-Object {
    $syncServices += $_.StorageSyncServiceName
}

if ($syncServices -notcontains $syncService) {
    throw [System.Exception]::new("The provided Storage Sync Service $syncService does not exist.")
}

# Check to make sure the provided Sync Group exists
$syncGroups = [System.String[]]@()

Get-AzStorageSyncGroup -ResourceGroupName $resourceGroup -StorageSyncServiceName $syncService | ForEach-Object {
    $syncGroups += $_.SyncGroupName
}

if ($syncGroups -notcontains $syncGroup) {
    throw [System.Exception]::new("The provided sync group $syncGroup does not exist.")
}

# Get reference to cloud endpoint
$cloudEndpoint = Get-AzStorageSyncCloudEndpoint `
    -ResourceGroupName $resourceGroup `
    -StorageSyncServiceName $syncService `
    -SyncGroupName $syncGroup

# Get reference to storage account
$storageAccount = Get-AzStorageAccount | Where-Object { 
    $_.Id -eq $cloudEndpoint.StorageAccountResourceId
}

if ($storageAccount -eq $null) {
    throw [System.Exception]::new("The storage account referenced in the cloud endpoint does not exist.")
}

Ensure the Azure file share exists.

$fileShare = Get-AzStorageShare -Context $storageAccount.Context | Where-Object {
    $_.Name -eq $cloudEndpoint.AzureFileShareName -and
    $_.IsSnapshot -eq $false
}

if ($fileShare -eq $null) {
    throw [System.Exception]::new("The Azure file share referenced by the cloud endpoint does not exist")
}

Ensure Azure File Sync has access to the storage account.

$role = Get-AzRoleAssignment -Scope $storageAccount.Id | Where-Object { $_.DisplayName -eq "Microsoft.StorageSync" }

if ($role -eq $null) {
    throw [System.Exception]::new("The storage account does not have the Azure File Sync " + `
                "service principal authorized to access the data within the " + `
                "referenced Azure file share.")
}

See also

• Troubleshoot Azure File Sync sync group management
• Troubleshoot Azure File Sync agent installation and server registration
• Troubleshoot Azure File Sync cloud tiering
• Monitor Azure File Sync
• Troubleshoot Azure Files problems