Fix Agent Installation Problems on Windows

When the octoja agent will not install on a Windows device, the answer is almost always in one of the installer's log files. This article shows you where those logs live and how to resolve the most common installation errors.

Where to find the logs

Common errors

Check firewall and web-filter logs

An open HTTPS port does not guarantee that downloads are allowed. For example, a FortiGate web filter can block an octoja hostname classified as uncategorized. Check the firewall or web-filter logs for the blocked destination and allow the required hosts according to your security policy. See the firewall reference for destinations.

Do not disable certificate validation or the entire web filter.

Reinstall the agent cleanly

A reinstall is the right move when the installation is broken — for example after the device was rolled back to a system restore point and the agent no longer connects, or when the agent files were partially removed.

First check the enrollment token's customer and site: on re-enrollment, the device adopts that assignment even if it previously belonged to another customer. A customer-bound token without a site clears the previous site. Without a customer-bound token, a valid existing assignment is preserved. See Configure Agent Enrollment Tokens for the full rules.

• On the device, open Settings → Apps → Installed apps, find octoja Agent, and uninstall it.
• If the entry is missing but the installer still reports "already installed", the Octoja.Launcher service is still registered. Follow Remove the Agent from a Device to take the remnants off the machine.
• Run the Quick Install command from Administration → Agent Deployment again. The device re-enrolls and reports back into Devices within 1–2 minutes.

Still stuck?

Check octoja Availability & Status for current known issues, and open a support case with the two install logs attached — they let support pinpoint the failing step immediately. Gather logs for a support case shows how.

FAQ

Does installing the .NET Runtime satisfy the installer’s .NET requirement?

No. The Windows installer requires .NET Framework 4.7.2 or later. The modern .NET Runtime does not replace it. Quick Install installs .NET Framework 4.7.2 automatically if the requirement is not met. If setup requires a restart, restart Windows and rerun Quick Install. For a manual MSI or Intune/GPO rollout, install the prerequisites before running the MSI.

What if the agent is running but enrollment is rejected because the enrollment token is missing?

Use these steps when the agent log shows enrollment rejected with HTTP 401 and An enrollment token is required. or Ein Enrollment-Token ist erforderlich. Running services alone do not confirm successful enrollment.

1. Under Administration → Agent Deployment, select a valid token for the intended customer and site. See Configure Agent Enrollment Tokens for the steps and required permissions.

2. On the affected Windows device, open %ProgramData%\octoja GmbH\launcherconfig.xml in a text editor with administrator rights. Inside the existing LauncherConfig element, add or replace only the EnrollmentToken element. Keep the capitalization exactly as shown and replace the placeholder with the valid token:

   Copy code

   <EnrollmentToken>YOUR_ENROLLMENT_TOKEN</EnrollmentToken>
   

3. Leave all other entries unchanged and save the file. With the device connected to your octoja instance, wait for the next automatic enrollment attempt. After repeated failures, this can take up to 15 minutes. Neither reinstalling nor restarting the service is needed for this token correction.

After successful enrollment, the agent removes the token from the file — this is normal. If enrollment still fails, check the new error in the agent log instead of removing more configuration entries. Do not share the token in screenshots or support attachments.