Folder Permission Migration Troubleshooting

1. Common Causes of Folder Permission Migration Issues

   1. Missing Destination Mailbox or User Objects

   Folder permissions are assigned to security principals such as user mailboxes, shared mailboxes, mail-enabled security groups, and mail contacts. During migration, these identities must be matched with corresponding objects in the destination environment. If a referenced mailbox or recipient does not exist, Exchange cannot apply the permission entry because the security identifier (SID) or Microsoft Entra ID object cannot be resolved.

   Common scenarios include:

   • Delegated mailbox has not yet been migrated.
   • User account has been deleted or disabled.
   • Mail contact is missing.
   • Guest account is unavailable.
   • Mail-enabled security group has not been created.

   2. Folder Hierarchy Mismatch

   Folder permissions are associated with specific mailbox folders rather than the mailbox itself. If the destination mailbox contains a different folder hierarchy, Exchange cannot associate the permission with the intended folder.

   Hierarchy inconsistencies can occur when:

   • Custom folders were not migrated.
   • Folder names were renamed.
   • Folder paths differ between source and destination.
   • Folder creation order changed during migration.
   • Parent folders are missing.

   3. Unsupported Permission Levels

   Exchange supports a defined set of mailbox folder permission roles, including predefined roles such as Reviewer, Author, Editor, Publishing Editor, Publishing Author, Nonediting Author, Owner, and custom permissions based on individual access rights. During migration, unsupported or incompatible permission configurations may not translate correctly between environments.

   This is more common when migrating:

   • Between different Exchange Server versions.
   • From Exchange Server to Exchange Online.
   • Between separate Microsoft 365 tenants.

   In some cases, custom permission combinations are converted to the closest supported permission level or require manual reassignment after migration. Administrators should review folders that use customised access rights before beginning the migration.

   4. Shared Mailbox Permission Dependencies

   Shared mailboxes frequently contain delegated access for multiple users across departments. Folder permissions can only be restored if both the shared mailbox and every delegated user are available in the destination environment.

   Permission migration may fail when:

   • The shared mailbox is migrated after user mailboxes.
   • Delegated users have not yet been created.
   • Mailbox GUID mapping is incomplete.
   • Shared mailbox conversion has not completed.

   A recommended migration sequence is:

   • Create or migrate shared mailboxes.
   • Provision delegated user accounts.
   • Synchronise directory objects.
   • Apply folder permissions.

   Following this order ensures that Exchange can resolve all permission references during migration.

   5. Cross-Tenant Identity Mapping Limitations

   Cross-tenant migrations introduce additional complexity because source object identifiers are not preserved in the destination Microsoft 365 tenant. Although user principal names (UPNs), SMTP addresses, or mapping files can be used to associate users, Exchange cannot automatically translate every security principal from one tenant to another.

   Common examples include:

   • Different UPN suffixes.
   • Renamed user accounts.
   • Recreated mailboxes.
   • Missing external identities.
   • Tenant-specific object identifiers.

   Without accurate identity mapping, folder permissions referencing source users cannot be recreated automatically. Administrators should verify recipient matching before running the permission migration phase.

   6. Public Folder Permission Inconsistencies

   Public folders use a permission model that differs from standard mailbox folders. In addition to folder-level permissions, organisations often implement nested public folder hierarchies, mail-enabled public folders, and inherited access permissions.

   Migration issues commonly occur when:

   • Public folder hierarchy is incomplete.
   • Parent folders were not migrated.
   • Mail-enabled public folders are missing.
   • Legacy permissions reference deleted users.
   • Folder replicas are inconsistent.

   Because public folders often contain historical permission entries accumulated over several years, administrators should audit permissions before migration and remove obsolete or unresolved entries where possible.

   7. Mail-Enabled Security Group Resolution Failures

   Organisations commonly assign folder permissions to mail-enabled security groups instead of individual users. This simplifies permission management but introduces additional validation requirements during migration.

   Permission restoration can fail if:

   • The security group has not been synchronized.
   • Group membership is incomplete.
   • The group was recreated with a different object identity.
   • Mail-enabled attributes are missing.

   Even if the group name appears identical, Exchange validates the destination recipient rather than relying solely on the display name. Administrators should verify that all mail-enabled security groups are synchronized and fully functional before migrating folder permissions.

   8. Microsoft Graph and Exchange API Limitations

   Folder permission migration relies on Exchange Web Services (EWS), Microsoft Graph, or Exchange administrative APIs to enumerate mailbox folders and retrieve permission entries. Depending on the migration scenario, these interfaces may impose throttling policies, pagination limits, or permission scope restrictions.

   Examples include:

   • Temporary API throttling during large-scale migrations.
   • Incomplete permission enumeration due to insufficient administrative roles.
   • Delayed visibility of recently provisioned mailboxes.
   • Transient service errors when querying Exchange Online.

   To reduce API-related failures, ensure that the migration account has the required Exchange administrative permissions, allow sufficient time for directory synchronization, and perform migrations in manageable batches where appropriate.

   9. Permission Inheritance and Legacy Entries

   Mailbox folders can contain explicitly assigned permissions as well as inherited or legacy access entries accumulated over years of administrative changes. Some folders may reference users or groups that no longer exist in the organization.

   These legacy entries can lead to:

   • Unresolved security principals.
   • Invalid permission records.
   • Skipped permission assignments.
   • Partial migration results.

   Before migrating, review folder permissions and remove obsolete delegates, deleted users, or unsupported permission entries. Cleaning the source environment helps ensure that only valid permissions are transferred and reduces post-migration troubleshooting.

2. Troubleshooting Folder Permission Migration

   When folder permissions are not migrated as expected, administrators should follow a structured troubleshooting process to identify whether the issue is related to the source environment, destination environment, identity mapping, or Exchange service limitations. Validating each component individually helps isolate the root cause and prevents repeated migration failures.

   1. Verify Destination Recipient Availability

   The first step is to confirm that every mailbox, shared mailbox, mail-enabled security group, and mail contact referenced in the source permissions exists in the destination environment.

   Verify the following:

   • User mailbox is provisioned and licensed (Exchange Online).
   • Shared mailbox exists and is accessible.
   • Mail-enabled security groups have synchronized successfully.
   • Mail contacts and guest users have been created where applicable.
   • User Principal Name (UPN) or primary SMTP address matches the intended destination recipient.

   If a recipient cannot be resolved, Exchange cannot apply the corresponding folder permission, and the migration application typically reports the entry as skipped or unresolved.

   2. Validate the Mailbox Folder Hierarchy

   Folder permissions are applied to specific mailbox folders. Even a minor difference in the destination folder structure can prevent permission assignment.

   Verify that:

   • All mailbox folders were migrated successfully.
   • Parent folders exist before child folders.
   • Folder names match exactly.
   • Folder paths remain unchanged.
   • Custom folders have been recreated correctly.

   3. Review Migration Logs for Permission-Related Errors

   Migration logs provide the most reliable method for determining why a permission entry was not migrated.

   Review the migration report for errors such as:

   • Recipient not found.
   • Folder not found.
   • Permission assignment failed.
   • Access denied.
   • Object resolution failed.
   • Insufficient permissions.
   • Throttling detected.
   • API timeout.

   Rather than focusing only on the overall migration status, review the detailed log entries associated with each mailbox. A mailbox may complete successfully while still containing skipped or failed permission entries. When using EdbMails, review the migration log after each migration batch to identify permission-related warnings before proceeding with additional mailbox migrations.

   4. Verify Administrative Permissions

   Folder permission migration requires administrative privileges to read permissions from the source environment and write permissions to the destination mailbox.

   Depending on the migration scenario, verify that the migration account has appropriate Exchange administrative roles.

   Examples include:

   • Full Access to the mailbox when required.
   • Exchange Organisation Management (Exchange Server).
   • Exchange Administrator role (Microsoft 365).
   • Application permissions when using Microsoft Graph.
   • Appropriate EWS access policies if Exchange Web Services is used.

   Insufficient permissions may allow mailbox data to migrate while preventing folder permissions from being enumerated or restored.

   5. Confirm Identity Mapping Accuracy

   Cross-tenant and hybrid migrations rely on accurate identity mapping between source and destination recipients.

   Verify that:

   • Source UPN matches the destination user.
   • Primary SMTP addresses are correct.
   • Mailbox aliases are unique.
   • User mapping files (if used) contain accurate values.
   • Duplicate recipient objects do not exist.

   Incorrect identity mapping is one of the most common causes of missing delegated access after migration. If recipients have been renamed during tenant consolidation, update the mapping information before rerunning the permission migration.

   6. Check Shared Mailbox Configuration

   Shared mailboxes should be fully operational before folder permissions are restored.

   Verify that:

   • The shared mailbox exists.
   • The mailbox has completed provisioning.
   • Delegated users exist.
   • Mailbox type is correctly configured as a shared mailbox.
   • Exchange Online synchronization has completed.

   Attempting to restore permissions before the shared mailbox becomes available may result in incomplete permission assignments.

   7. Validate Public Folder Permissions Separately

   Public folders use a different permission model from mailbox folders and should be validated independently.

   Confirm that:

   • The complete public folder hierarchy exists.
   • Parent folders were migrated first.
   • Mail-enabled public folders were recreated where applicable.
   • Legacy permission entries have been removed.
   • Replication has completed across Exchange servers, if applicable.

   Do not assume mailbox permission validation also confirms public folder permissions.

   8. Monitor Exchange Throttling and Service Limits

   Large-scale migrations may trigger Exchange Online throttling policies or API request limits.

   Common indicators include:

   • Temporary migration pauses.
   • Retry operations.
   • Delayed permission application.
   • Service unavailable responses.
   • Request timeout errors.

   If throttling occurs:

   • Reduce the number of concurrent mailbox migrations.
   • Migrate permissions in smaller batches.
   • Allow retry operations to complete.
   • Schedule migrations during lower activity periods where possible.

   Transient throttling errors often resolve automatically without requiring manual intervention.

   9. Perform Post-Migration Permission Verification

   After the migration completes, validate that permissions have been restored correctly rather than relying solely on migration reports.

   Verify the following:

   • Users can access delegated folders.
   • Calendar delegates retain their assigned access.
   • Shared mailbox folders open successfully.
   • Custom folder permissions match the source mailbox.
   • Public folder permissions are preserved.
   • Mail-enabled security groups continue to provide the expected access.
   • No folders display missing delegate information.

   Where practical, compare a representative sample of source and destination mailbox permissions to ensure that permission levels and assigned users are identical.

3. Best Practices Before Folder Permission Migration

   Performing validation before migrating folder permissions significantly reduces permission mapping failures and minimises post-migration administrative effort. The following recommendations help ensure that the source and destination environments are prepared for a successful migration.

   • Verify recipient readiness: Confirm that all user mailboxes, shared mailboxes, mail-enabled security groups, distribution groups (where applicable), and mail contacts referenced in folder permissions exist in the destination environment.
   • Complete directory synchronisation: In hybrid deployments, ensure that Microsoft Entra Connect (or the applicable synchronisation solution) has completed successfully and that all recipient objects are synchronised before migrating permissions.
   • Migrate mailbox content before permissions: Folder permissions should be migrated only after mailbox folders and their hierarchy have been successfully copied. Missing folders can prevent permissions from being applied.
   • Review existing folder permissions: Audit mailbox folders to identify obsolete delegates, deleted users, unresolved security principals, and duplicate permission entries. Removing invalid permissions before migration improves migration accuracy.
   • Validate custom folder structures: Ensure that custom folders, nested folders, and non-default mailbox folders are included in the migration scope. Folder path discrepancies can prevent permission assignment.
   • Confirm administrative access: Verify that the migration account has sufficient Exchange administrative permissions to enumerate source permissions and write permissions to destination mailboxes.
   • Plan mailbox migration order: Where delegated access exists, migrate dependent mailboxes in a logical sequence. For example, migrate shared mailboxes and delegated user accounts before restoring folder permissions.
   • Perform a pilot migration: Test folder permission migration with a small set of representative mailboxes before processing the entire migration batch. A pilot migration helps identify mapping or configuration issues early.

4. Best Practices After Folder Permission Migration

   After permissions have been migrated, perform validation to confirm that users retain the expected level of access and that no permission entries were skipped or incorrectly mapped.

   • Review migration reports for warnings, skipped permission entries, or unresolved recipients.
   • Compare a representative sample of source and destination folder permissions.
   • Verify delegated access for Calendar, Inbox, Contacts, Tasks, and custom folders.
   • Confirm that shared mailbox permissions have been restored correctly.
   • Validate public folder permissions separately from mailbox folder permissions.
   • Check that mail-enabled security groups continue to grant the intended access.
   • Remove obsolete permission entries that are no longer required.
   • Document any manually recreated permissions for future administrative reference.
   • Allow sufficient time for Exchange Online directory replication before performing final validation, particularly after large-scale migrations.
   • Retain migration logs until administrator validation is complete.

Conclusion

Folder permission migration is a critical component of Exchange and Microsoft 365 mailbox migrations because it preserves delegated access to mailbox folders, shared mailboxes, and public folders. Unlike mailbox data migration, permission migration depends on successful recipient resolution, consistent folder hierarchy, supported permission models, and adequate administrative privileges.

Most permission migration issues can be traced to unresolved destination recipients, missing mailbox folders, identity mapping inconsistencies, incomplete directory synchronisation, or Exchange service limitations. Following a structured troubleshooting approach—beginning with recipient validation, folder hierarchy verification, migration log analysis, administrative permission checks, and post-migration testing—allows administrators to identify and resolve issues efficiently.

Before running Folder Permission Migration in EdbMails, ensure that the source environment has been audited, destination recipient objects are fully provisioned, and mailbox data has been migrated successfully. After migration, validate delegated access using migration reports and functional testing to confirm that permissions have been accurately restored and that users retain uninterrupted access to the folders required for their daily operations.