Troubleshooting Microsoft 365 Tenant Hydration and Organization Settings Customization Errors in INKY

Overview

This article helps troubleshoot Microsoft 365 onboarding issues where INKY cannot complete tenant hydration, group analysis, or organization settings customization.

These errors can prevent a customer from completing INKY setup and may block implementation, billing, migration, or mail filtering cutover.

Use this article if you see errors or symptoms such as:

• Tenant hydration failed
• Organization settings customization failed
• Installer cannot verify Microsoft 365 tenant settings
• Error getting groups to analyze for compatibility
• Setup cannot continue after connecting Microsoft 365
• Groups are not loading or cannot be analyzed
• Customer cannot complete onboarding
• Customer is not protected because setup did not complete
• INKY cannot validate Microsoft 365 tenant configuration

What tenant hydration means

During Microsoft 365 onboarding, INKY needs to read and validate information from the customer tenant so it can prepare the organization for configuration.

This may include checking:

• Microsoft 365 tenant access
• Global Admin authorization
• Required permissions
• User and group data
• Include/exclude or rollout group compatibility
• Organization settings
• Mail routing readiness
• Existing tenant configuration that may affect INKY setup

If INKY cannot read or validate this information, onboarding may stop before the customer is fully configured.

Important: Do not cut over mail until setup is validated

If tenant hydration or organization settings customization has failed, do not route production mail through INKY until setup and mail flow have been validated.

Before go-live, confirm:

• The customer tenant is connected successfully.
• Required settings have been applied.
• Users and groups are recognized correctly.
• Test mail routes as expected.
• Protected users receive mail.
• INKY banners appear where expected.
• Microsoft 365 Message Trace confirms expected mail flow.

If the customer is already live and mail filtering is not working, review routing immediately and confirm whether mail is flowing through INKY, Microsoft 365, another gateway, or no filtering path.

Step 1: Confirm the exact error

Start by capturing the exact error message shown during setup.

Common examples may include:

• Tenant hydration failed
• Organization settings customization failed
• Error getting groups to analyze for compatibility
• Unable to verify tenant settings
• Unable to retrieve groups
• Unable to complete organization setup

Record:

• The exact error text
• The step where the error occurred
• Date and time of the failure
• Customer tenant name
• Microsoft 365 tenant ID, if available
• Admin account used for setup
• Whether this is a new setup, migration, retry, or offboarding/re-onboarding scenario

Step 2: Confirm Microsoft 365 admin access

Tenant hydration may fail if the admin account used during setup does not have the required access.

Check:

• The admin account belongs to the correct Microsoft 365 tenant.
• The admin account is active and licensed if required by your process.
• The admin account has the required Microsoft 365 admin role.
• The admin account can access the Microsoft 365 admin center.
• The admin account can view users and groups.
• The admin account can view Exchange admin settings if needed.
• The admin account is not blocked by Conditional Access, MFA, or security policy during authorization.

If the setup was attempted with the wrong admin account or wrong tenant, retry using an account with the correct tenant-level permissions.

Step 3: Confirm app consent and permissions

INKY may require Microsoft app consent or delegated permissions to read tenant information and apply configuration.

Check:

• Admin consent was granted successfully.
• The consent prompt completed without error.
• The INKY enterprise application appears in Microsoft Entra ID, if applicable.
• Required permissions were not removed or blocked.
• No Conditional Access policy is preventing the authorization.
• The admin account did not cancel or partially complete the consent flow.

If app consent was interrupted or completed with the wrong account, remove the failed/partial connection if needed and retry the authorization process.

Step 4: Review Microsoft 365 groups

If the error mentions groups, group analysis, or compatibility, review the customer’s Microsoft 365 groups.

Check:

• Required include/exclude groups exist.
• Group names match what was entered during setup.
• Groups are mail-enabled if required by the deployment process.
• Groups contain the expected users.
• Groups do not contain stale, deleted, or invalid users.
• Groups do not rely on unsupported nesting.
• Dynamic groups are supported for the intended use case, if used.
• Security groups, distribution groups, Microsoft 365 groups, and mail-enabled security groups are being used appropriately.
• The admin account can view the groups in Microsoft 365 or Entra ID.

If INKY cannot retrieve or analyze the group, test with a simpler group containing a small number of known active users.

Step 5: Check for stale or invalid directory objects

Tenant hydration can fail when Microsoft 365 returns unexpected or invalid directory objects.

Review whether the tenant has:

• Deleted users still appearing in groups
• Disabled users in rollout groups
• Guest users in groups
• External contacts in groups
• Nested groups
• Dynamic membership rules
• Very large groups
• Groups with no members
• Duplicate or conflicting group names
• Old migration artifacts from previous tools
• Incomplete directory synchronization

If possible, test with a clean group that contains only a few active internal users.

Step 6: Confirm organization settings can be customized

If the error mentions organization settings customization, INKY may be unable to apply or verify required settings.

Check:

• The Microsoft 365 tenant is reachable.
• Admin consent is still valid.
• Required admin role is assigned.
• No Microsoft service health issue is affecting tenant configuration.
• Existing transport rules, connectors, or security policies are not conflicting with setup.
• Another admin has not changed or removed required settings during setup.
• Previous INKY, Graphus, or third-party email security configuration is not partially removed.

If this is a migration, confirm whether old connectors, transport rules, routing rules, or security platform settings need to remain temporarily or be removed before setup continues.

Step 7: Check Microsoft service health and tenant availability

If setup previously worked but now fails, check Microsoft service health and tenant availability.

Review:

• Microsoft 365 service health
• Exchange Online service health
• Entra ID service health
• Any active incidents affecting admin APIs, group retrieval, or Exchange configuration
• Whether other admin actions in the tenant are also failing

Step 8: Retry the setup carefully

After correcting access, group, or tenant issues, retry setup.

Before retrying:

• Use the correct Microsoft 365 admin account.
• Confirm the admin account has the required role.
• Confirm groups are clean and visible.
• Confirm app consent can be granted.
• Clear any failed or partial setup state if instructed by INKY documentation or support.
• Avoid making unrelated tenant changes while setup is running.

During retry:

• Capture screenshots of each step.
• Record the timestamp of any failure.
• Note whether the error is the same or different.
• Confirm whether the failure occurs before or after group selection/customization.

Step 9: Validate after setup completes

After tenant hydration and organization customization complete, validate the deployment before considering setup finished.

Check:

• Customer appears correctly in INKY.
• Expected users/groups are visible.
• Include/exclude or rollout groups are recognized.
• Routing is configured correctly.
• Test messages are delivered.
• INKY banners appear where expected.
• Microsoft 365 Message Trace shows expected routing.
• No unexpected quarantine, rejection, or mail loop occurs.
• Admins know where to check message trace, quarantine, and observations.

Common causes

Information to gather before contacting support

If setup still fails, gather the following:

• Customer name
• Microsoft 365 tenant ID
• Customer domain
• Setup stage where the failure occurred
• Exact error message
• Screenshot of the error
• Date and time of the failure, including time zone
• Admin account used for setup
• Whether admin consent was completed
• Whether the INKY enterprise application appears in Microsoft Entra ID, if applicable
• Group name or group ID involved in the error
• Group type and membership details
• Whether nested, dynamic, guest, disabled, or deleted users are present in the group
• Whether this is a new onboarding, migration, retry, offboarding, or re-onboarding
• Whether any previous INKY, Graphus, or third-party mail security configuration exists
• Microsoft service health status, if relevant
• Screenshots of relevant Microsoft 365 connectors, transport rules, or routing settings
• Microsoft 365 Message Trace results for any test messages, if mail routing was attempted