Troubleshooting 365TUNE Hybrid Agent Installation and Registration

This article explains how to resolve common installation, connectivity, authentication, and registration issues with the 365TUNE Hybrid Agent.

The Hybrid Agent connects your on-premises Active Directory environment to 365TUNE. During installation, the setup wizard checks your server's configuration and identifies any issues that could prevent the agent from installing or registering successfully.

Follow the troubleshooting steps below to resolve errors and complete the setup.

Applies to: 365TUNE Hybrid Agent installer version 1.0.11 and later. Some troubleshooting steps also apply to earlier versions.

1. Understanding the Installation Checks

When you launch the Hybrid Agent installer, it automatically checks whether your server meets the requirements for installation and registration.

These checks run:

When you first launch the installer.
When you select Check again.
Before starting agent registration.
When you reopen 365TUNE Hybrid Agent from the Windows Start menu.
When you select Register again on the Connected screen.

Understanding check results

The installer displays two types of issues:

Status	Meaning	Action required
Error	A requirement has not been met. Installation cannot continue.	Resolve the issue and select Check again.
Warning	A potential issue or additional requirement has been identified.	Review the warning. You can continue installation, but registration may require additional action.

Successful checks disappear automatically, allowing you to focus on items that need attention.

Important: These preliminary checks are read-only and do not modify Active Directory. During the checks, the installer makes HTTPS connectivity requests to Microsoft's sign-in service and the 365TUNE API.

2. Prerequisites for Installing the Hybrid Agent

Before installing the agent, ensure that your server meets the following requirements.

Requirement	Description
Active Directory membership	The server must be joined to an Active Directory domain.
Windows account	Sign in using a domain account with the necessary permissions or access to an AD administrator account.
Domain controller	A writable domain controller must be accessible.
Time synchronization	The server clock must be synchronized with the domain controller.
Active Directory PowerShell	The RSAT Active Directory PowerShell module must be installed.
WebView2 Runtime	Microsoft Edge WebView2 Runtime is required for authentication.
.NET 8 Runtime	Required by the agent; included in the installation package.
Network connectivity	Outbound HTTPS access to Microsoft sign-in services and the 365TUNE API.
KDS root key	A usable KDS root key is required to create a group Managed Service Account (gMSA).

Recommended deployment: Install the Hybrid Agent on a domain-joined Windows member server rather than directly on a domain controller.

3. Resolving Installation Errors

The following errors prevent installation from continuing.

After resolving an error, return to the installer and select Check again.

Error: Windows session is not a domain account

Message displayed:

"Signed in as DOMAIN\user, an Entra ID account (or a local account). Sign in to Windows with a domain account to register."

Why this happens

The installer detects that you are signed in to Windows using a local computer account or Microsoft Entra ID account instead of an Active Directory domain account.

The Hybrid Agent registration process creates a group Managed Service Account and configures Active Directory permissions. These operations require domain access.

How to resolve

Sign out of the current Windows session.
Sign in using an Active Directory domain account.
Preferably use a Domain Administrator account or an account with delegated permissions to create service accounts and manage the required organizational units (OUs).
Launch the installer again.

If your domain account does not have Domain Administrator permissions, you may be prompted to provide separate Active Directory administrator credentials during registration.

Error: Server is not joined to a domain

Message displayed:

"This server is not joined to an Active Directory domain. Join it to the domain first."

Why this happens

The Hybrid Agent requires an Active Directory domain because it uses a group Managed Service Account to run its Windows service.

Servers joined only to Microsoft Entra ID or configured in a workgroup cannot host the agent.

How to resolve

Join the server to your Active Directory domain.
Restart the server.
Sign in with a domain account.
Run the installer again.

You can join the server using PowerShell with administrator privileges:

Add-Computer -DomainName corp.example.com -Credential corp\admin -Restart

Replace the example domain and account with your organization's information.

Error: Domain controller unreachable

Message displayed:

"No writable domain controller for DOMAIN answered this server as DOMAIN\user. Check the domain name, DNS and the session account."

Why this happens

The installer cannot locate or communicate with a writable domain controller for the selected Active Directory domain.

This may be caused by incorrect DNS configuration, firewall restrictions, an incorrect domain name, or insufficient connectivity.

How to resolve

Step 1: Verify DNS configuration

Check the DNS servers configured on your server:

Get-DnsClientServerAddress

Verify that Active Directory domain controller records resolve correctly:

Resolve-DnsName _ldap._tcp.dc._msdcs.corp.example.com -Type SRV

Step 2: Verify domain controller availability

Run:

nltest /dsgetdc:corp.example.com /writable

This checks whether a writable domain controller can be located.

Step 3: Verify the domain name

Confirm that you entered the correct Active Directory DNS domain name, such as corp.example.com.

If your environment contains multiple domains, select the domain in which you want the agent registered.

Step 4: Check firewall connectivity

Ensure that the server can communicate with Active Directory services using the required ports, including:

LDAP: TCP 389
LDAPS: TCP 636
Kerberos: TCP/UDP 88
SMB: TCP 445
RPC: Required RPC endpoint and dynamic ports

After correcting the configuration, select Check again.

Error: Server clock is out of sync

Message displayed:

"This server's clock differs from DC by N minutes; Kerberos and token validation need less than 5. Sync the time."

Why this happens

The server's clock differs from the domain controller by too much.

Active Directory authentication uses Kerberos, which normally requires clocks to remain within five minutes of each other. Incorrect time can also affect authentication token validation.

How to resolve

Resynchronize the server clock:

w32tm /resync

Check the time difference:

w32tm /stripchart /computer:dc01.corp.example.com /samples:3

If the issue continues, configure the server to use the domain time hierarchy:

w32tm /config /syncfromflags:domhier /update

Restart the Windows Time service:

Restart-Service w32time

Replace the example domain controller name with your actual domain controller.

Error: KDS root key is missing

Message displayed:

"The forest has no KDS root key. A Domain Admin must run Add-KdsRootKey; a new key is usable 10 hours later."

Why this happens

Active Directory requires a Key Distribution Service (KDS) root key before group Managed Service Accounts can be created.

If no KDS root key exists, the Hybrid Agent cannot create its service account.

How to resolve

Sign in to a domain controller with Domain Administrator privileges.
Open PowerShell with administrator privileges.
Run:
```
Add-KdsRootKey -EffectiveImmediately
```
Allow approximately 10 hours for the key to become usable across domain controllers.
Restart the registration process.

If you are running the installer using a Domain Administrator account, registration can create a missing KDS root key automatically. However, the key must become usable before service account creation can succeed.

Important: In a single-domain-controller test environment, Microsoft provides a method to create a backdated KDS key. This method should not be used in production.

Error: Active Directory PowerShell module is missing

Message displayed:

"Not installed. Run: Install-WindowsFeature RSAT-AD-PowerShell."

Why this happens

The Active Directory PowerShell module is required to create and configure the agent's group Managed Service Account.

How to resolve

Open PowerShell as an administrator on the Windows Server and run:

Install-WindowsFeature RSAT-AD-PowerShell

Once installation completes, return to the setup wizard and select Check again.

A server restart is not normally required.

Error: Microsoft Edge WebView2 Runtime is missing

Message displayed:

"The WebView2 runtime is missing; the 365TUNE sign-in cannot be shown. Install the Evergreen WebView2 runtime from Microsoft."

Why this happens

The Hybrid Agent setup wizard uses Microsoft Edge WebView2 to display the Microsoft sign-in page during registration.

Some Windows Server installations do not include this runtime.

How to resolve

Visit the official Microsoft Edge WebView2 download page.
Download the Evergreen Bootstrapper or Evergreen Standalone Installer.
Install the runtime on the server.
Return to the Hybrid Agent installer.
Select Check again.

For servers without direct internet access, download the Evergreen Standalone Installer on another computer and transfer it to the server.

Error: Microsoft sign-in service is unreachable

Message displayed:

"login.microsoftonline.com could not be reached over HTTPS, or did not answer within 20 s. Allow outbound HTTPS from this server, or check DNS, the proxy and TLS inspection."

Why this happens

The installer cannot reach the Microsoft authentication service.

Common causes include:

Outbound HTTPS traffic is blocked.
Incorrect DNS configuration.
Proxy configuration issues.
TLS inspection or certificate trust issues.
Network connectivity problems.

How to resolve

Step 1: Test connectivity

Run the following command from the server:

curl.exe -s -o NUL -w "%{http_code}" https://login.microsoftonline.com/common/.well-known/openid-configuration

A three-digit HTTP response confirms that the server received an HTTP response from the endpoint.

If the command reports a DNS resolution failure, verify that the server can resolve public domain names.

Step 2: Check proxy configuration

If your organization uses an internet proxy, verify that the server and installing user have the appropriate proxy settings.

Step 3: Review TLS inspection

If your organization performs TLS inspection, ensure that the inspection certificate is trusted or that the Microsoft authentication endpoint is appropriately excluded.

Step 4: Review firewall rules

Allow outbound HTTPS traffic on TCP port 443 to:

login.microsoftonline.com

Retry the connectivity check before continuing.

Error: 365TUNE API is unreachable

Message displayed:

"app.365tune.com could not be reached over HTTPS, or did not answer within 20 s. Allow outbound HTTPS from this server, or check DNS, the proxy and TLS inspection."

Why this happens

The server cannot communicate with the 365TUNE API.

The agent requires this connection to complete registration, submit certificate requests, and communicate with the 365TUNE platform after installation.

How to resolve

Confirm that the server has outbound HTTPS access.
Allow app.365tune.com through your firewall or proxy.
Check DNS resolution.
Review TLS inspection and certificate trust.

Test connectivity using:

curl.exe -s -o NUL -w "%{http_code}" https://app.365tune.com/agent-api/

Any HTTP response confirms that the endpoint is reachable at the HTTP level. It does not necessarily confirm successful authentication.

After resolving connectivity issues, select Check again.

4. Understanding Installation Warnings

Warnings do not prevent installation, but they may indicate additional requirements before registration can complete.

Warning: Windows account is not a Domain Administrator

Message displayed:

"DOMAIN\user is not a Domain Admin of DOMAIN. Registration will ask for an Active Directory administrator account."

What this means

The Windows account being used is not a member of the Domain Admins or Enterprise Admins groups.

The agent registration process requires permissions to:

Create the group Managed Service Account.
Update the service account configuration.
Configure the required permissions on selected Active Directory OUs.

What to do

During the Connect step, you can provide a separate Active Directory administrator account with the required permissions.

These credentials are used for registration and are not included in command-line arguments or logs.

If your Windows account already has the necessary delegated permissions, you may leave the additional credential fields empty and continue. The registration process will verify the permissions.

Warning: KDS root key is not yet usable

Message displayed:

"A KDS root key exists but is usable from DATE TIME. gMSA creation fails until then."

What this means

A KDS root key has been created but is not yet available for service account creation.

What to do

Wait until the time displayed by the installer, then attempt registration again.

Warning: Installing on a domain controller

Message displayed:

"This server is a domain controller. The agent is designed for a member server; running it here places a third-party service on a Tier 0 host. Suitable for a lab, not recommended in production."

What this means

The server is an Active Directory domain controller.

What to do

For production environments, install the Hybrid Agent on a dedicated domain-joined member server instead.

Installing additional services directly on domain controllers can introduce unnecessary security and operational risks.

Warning: Server is already registered

Message displayed:

"This server is already registered. Registering again replaces its certificate and configuration."

What this means

The Hybrid Agent is already registered with 365TUNE.

What to do

Continue only if you intend to re-register the agent.

Re-registration replaces the existing registration certificate and configuration.

5. Installing the .NET 8 Runtime

The 365TUNE Hybrid Agent requires Microsoft .NET 8 Runtime.

If it is missing, the installer displays:

".NET 8 Runtime missing. The Microsoft .NET 8 Runtime is included with this setup. Install now"

The required runtime installer is included in the Hybrid Agent installation package.

You do not need to download it separately.

Available options:

Install now: Installs the .NET 8 Runtime immediately and reruns the prerequisite checks, even if other checks are failing.
Install: Installs the runtime along with the Hybrid Agent once all blocking checks have passed.

The .NET 8 Runtime remains installed if you later uninstall the Hybrid Agent.

6. Troubleshooting Microsoft Sign-In Errors

After completing the installation checks, you must authenticate with 365TUNE to register the agent.

If authentication fails, review the error message and follow the applicable steps.

Sign-in failed: Access is denied (E_ACCESSDENIED)

Cause: The embedded sign-in browser cannot create its required working directory.

Resolution:

Use installer version 1.0.7 or later, which includes a fix for this issue.
If using an older version, run the installer from a folder where your Windows account has write permissions.

Sign-in failed [authentication_canceled]

Cause: The authentication window was closed before sign-in was completed.

Resolution:

Select Sign in with 365TUNE again and complete authentication.

Only a security key is offered during sign-in

Cause: Your organization's Microsoft Entra ID authentication policy requires phishing-resistant authentication, but the server may not have an available Windows Hello, passkey, or supported security key.

Resolution:

Contact your Microsoft Entra ID administrator to confirm an approved authentication method for registration.

Where permitted by your organization's policies, use a supported authentication method or perform registration on a server that supports the required security key.

A separate-device sign-in option is planned for a future release.

Enter the Active Directory administrator account and its password

Cause: Your Windows account is not a Domain Administrator, and the required administrator credential fields have not been completed.

Resolution:

Provide the requested Active Directory administrator credentials, or sign in to Windows using an appropriate administrator account and rerun the prerequisite checks.

Installer did not supply a sign-in token within 10 seconds

Cause: The registration process started but did not receive the authentication token within the expected time.

Resolution:

Select Back.
Choose Sign in with 365TUNE again.
Complete authentication.
If the error continues, review %TEMP%\365TuneSetup.log.

7. Troubleshooting Agent Registration Errors

Registration issues may occur during the Configuring step, after installation and authentication.

If registration fails, the wizard offers the following options:

Back: Return to the Connect step to review credentials or choose another domain.
Switch account: Sign in using a different Microsoft Entra ID account.
Finish without registering: Complete installation and register later using the 365TUNE Hybrid Agent entry in the Windows Start menu.

Error: Cannot reach the Active Directory domain

Message displayed:

"Cannot reach the current AD domain" or "Cannot reach AD domain 'NAME'"

Resolution:

Confirm that:

The server is joined to Active Directory.
You are signed in using a domain account.
The selected domain name is correct.
A writable domain controller is available.
DNS and firewall settings allow communication with the domain controller.

Refer to Domain controller unreachable in Section 3 for detailed troubleshooting.

Error: Registration requires Administrator rights

Cause: The Windows User Account Control (UAC) elevation request was declined or dismissed.

Resolution:

Restart the registration sign-in process and accept the administrator elevation prompt.

Error: Failed to contact 365TUNE API

You may see:

"Failed to contact 365TUNE API" or "Registration failed: HTTP status"

Resolution depends on the response:

Response	Possible cause	Recommended action
HTTP 401 or 403	The signed-in account is not authorized as a tenant administrator in 365TUNE.	Verify your account's permissions and use an authorized administrator account.
HTTP 5xx	A server-side service error occurred.	Retry registration later. Contact support if the issue continues.
Connection error	The 365TUNE API cannot be reached.	Review DNS, proxy, firewall, and outbound HTTPS connectivity.

Error: No authorized organizational units configured

Message displayed:

"Registration cancelled: no Authorised OUs configured"

Why this happens

No Active Directory organizational units have been selected for this agent in the 365TUNE portal.

How to resolve

Sign in to the 365TUNE portal.
Open the configuration for the Hybrid Agent.
Select at least one authorized organizational unit (OU).
Save the configuration.
Return to the installer and retry registration.

Error: gMSA setup failed at step N

The Hybrid Agent uses a group Managed Service Account (gMSA) to run its Windows service.

During registration, the installer completes nine configuration steps. A failure at any step may prevent registration.

Use the reported step number to identify the problem.

Step	Operation	Possible cause and resolution
1	Checking KDS Root Key	The KDS root key is missing or the account cannot create it. Configure the KDS root key as described in Section 3.
2	Creating gMSA in Active Directory	The account lacks permission to create service accounts, the AD PowerShell module is missing, or the KDS key is not yet usable.
3	Granting the server access to retrieve the gMSA password	The account cannot modify the service account object. Verify AD permissions.
4	Installing the gMSA on the server	The computer may not yet have permission to retrieve the password, or AD replication is incomplete. Allow replication and retry.
5	Resolving the gMSA security identifier (SID)	AD replication may be incomplete, or the wrong domain was selected. Verify the domain and retry.
6	Granting access to the agent directory	The registration account lacks local administrator permissions, or the agent folder permissions were modified.
7	Granting access to the certificate private key	The service account cannot access the certificate's private key. Retry registration with local administrator permissions.
8	Granting "Log on as a service" permission	Group Policy may override local user rights. Configure the applicable policy to allow the service account to log on as a service.
9	Applying Active Directory delegation	The registration account cannot modify permissions on one or more selected OUs. Provide the required permissions or use an AD administrator account.

Tip: If registration fails because of Active Directory replication delays, allow replication to complete before retrying.

Error: Could not write agent.json

Cause: The installer cannot write its configuration file to the agent directory under Program Files.

This may be caused by antivirus software, application control, or file permissions.

How to resolve

Verify that the registration process has local administrator permissions.
Check whether antivirus or application control software is blocking file creation.
Configure an approved allow rule or exclusion for the agent directory if necessary.
Retry registration.

Error: Windows Service start failed

Cause: The Hybrid Agent Windows service could not start after installation.

How to resolve

Open Event Viewer.
Navigate to Applications and Services Logs.
Open 365TuneHybridADAgent.
Review the latest startup errors.

Common causes include:

The gMSA does not have Log on as a service permissions.
The agent cannot access its certificate private key.

Resolve the issue reported in the event log and retry.

8. Troubleshooting Agent Connectivity After Registration

After successful registration, opening 365TUNE Hybrid Agent from the Start menu displays the Connected screen.

If the agent is registered but cannot communicate with 365TUNE, you may see:

"Registered with 365TUNE, not connected"

The following are common causes.

Agent service is stopped

Open the Windows Services console and locate:

365TUNE Hybrid AD Agent

Start the service.

Alternatively, open PowerShell as an administrator and run:

Start-Service 365TuneHybridADAgent

Check the connection status again.

Agent has not completed its first heartbeat

The Hybrid Agent sends a heartbeat to 365TUNE approximately every minute.

If the service has just started, allow a short period for the first successful heartbeat.

Refresh the connection status afterward.

Last heartbeat failed

The Connected screen may display the time of the last successful heartbeat and a reason for the latest failure.

Common causes include:

Outbound HTTPS connectivity has been interrupted.
Firewall or proxy settings have changed.
The agent registration certificate has expired.
The agent service is encountering an error.

Recommended troubleshooting:

Confirm that the agent service is running.
Test HTTPS connectivity to app.365tune.com.
Review the agent event log.
Check whether the registration certificate is valid.
Re-register the agent if certificate replacement is necessary.

Note for older installations: Servers registered before installer version 1.0.9 may not have a local registration record. In this case, the Start menu entry may open the Connect step instead of the Connected screen. Registering again creates the required record.

9. Finding Installation and Agent Logs

If troubleshooting does not resolve the issue, installation and service logs can help identify the cause.

Installer log

Location:

%TEMP%\365TuneSetup.log

This log records installation checks, results, and other setup events.

The log is stored in the temporary directory of the Windows account that ran the installer.

In installer version 1.0.11 and later, each prerequisite check run also includes a completion time entry.

Registration errors

Registration details may be available in:

The registration tool's console output.
Windows Event Viewer under Applications and Services Logs > 365TuneHybridADAgent.

Agent service logs

Open:

Event Viewer > Applications and Services Logs > 365TuneHybridADAgent

This log contains service startup and runtime events.

For example, Event ID 2006 indicates that environment configuration overrides were ignored.

10. Contacting 365TUNE Support

If the issue continues after completing the recommended troubleshooting steps, contact the 365TUNE support team.

To help us investigate, provide:

Error message: The exact message displayed by the installer or registration wizard.
Installer log: A copy of %TEMP%\365TuneSetup.log.
Windows Server version: The operating system version of the server hosting the agent.
Server role: Whether the server is a domain controller or member server.
Troubleshooting performed: A brief description of the steps you have already tried.

If the issue relates to the Windows service, include relevant events from the 365TuneHybridADAgent event log.

Review logs before sharing them to ensure they do not contain sensitive information.

Support: Contact 365TUNE

Frequently Asked Questions

Can I install the Hybrid Agent on a domain controller?

The installer can run on a domain controller, but this is not recommended for production environments. Use a domain-joined member server to reduce security and operational risks.

Do I need Domain Administrator permissions to install the agent?

Not necessarily. You can sign in using a domain account with the required delegated permissions. If additional permissions are needed during registration, the installer can request separate Active Directory administrator credentials.

Some operations, such as creating a missing KDS root key, have additional privilege requirements.

Does the installer modify Active Directory during the prerequisite checks?

No. The preliminary server checks are read-only.

Active Directory changes occur during registration, when the agent's service account and authorized OU permissions are configured.

Does the Hybrid Agent require internet access?

The agent requires outbound HTTPS connectivity to Microsoft's authentication services during registration and to the 365TUNE API for registration and ongoing communication.

If your organization uses a proxy or restrictive firewall, ensure the required endpoints are accessible.

Can I install the agent without completing registration?

Yes. If registration fails, you can select Finish without registering and complete registration later.

To register afterward, open 365TUNE Hybrid Agent from the Windows Start menu.

Will reinstalling the agent automatically resolve registration errors?

Not always. Many registration errors are caused by Active Directory permissions, DNS, domain controller connectivity, or network restrictions.

We recommend resolving the underlying error before reinstalling or attempting registration again.