Skip to content
Avanet

Troubleshoot Sophos Endpoint installation on macOS

Sophos Endpoint

This runbook starts with the visible symptom and deliberately separates installation, registration and configuration. Use the macOS installation guide for a normal first installation; use this page when that workflow fails or remains incomplete.

Quick symptom route

  • macOS does not open the installer, or the download bar ends without installation: check source, signature and quarantine first.
  • The diagnostic log says Folder Insecurity or path is not secure: record the path and current permissions read-only; do not apply a blanket repair.
  • Software is installed but the Mac is absent from Sophos Fusion: check Registration Status to Sophos Central, then network, proxy, time and tenant.
  • The Mac is visible in Sophos Fusion but remains red: identify the specific missing approval under Sophos Endpoint > About > Open Endpoint Self Help Tool > Prerequisites.
  • Updates fail: distinguish Updater permission from Management Communication first; do not delete agent files.

Before changing anything, record the exact error, affected stage, macOS and agent versions, and time. This makes it possible to tell whether the next action fixes the same cause.

Check installer trust and quarantine safely

Use only SophosInstall.zip from the correct Sophos Fusion (formerly Sophos Central) tenant. If Sophos Installer.app is in ~/SophosInstall, this read-only query lists its attributes:

xattr ~/SophosInstall/Sophos\ Installer.app

com.apple.quarantine, particularly after Safari automatically extracts an archive, can lead to App Translocation and failure. Remove it only when the installer came directly from the organisation’s own tenant and passed the signature checks in the installation guide:

sudo xattr -r -d com.apple.quarantine \
  ~/SophosInstall/Sophos\ Installer.app

The command is deliberately limited to this app bundle. Do not remove attributes recursively from Downloads, disable Gatekeeper globally, or continue after a rejected or differing signature. Download a fresh installer from the organisation’s tenant instead.

Stop safely at Folder Insecurity

Folder Insecurity is not an ordinary write error. The installer stops when a parent path is writable by an unsafe party, because a privileged installation could then adopt foreign files. The diagnostic entry normally names the insecure path, such as /Library.

Record ownership and mode read-only:

ls -la /
ls -la /Library

The documented secure values are 755 root:wheel for / and /Library, and 755 root:admin for /Library/Application Support. The error can also name /Library/Caches or a Sophos subdirectory. Compare the exact path reported with an equivalent healthy Mac and determine which imaging, packaging or management tool changed it.

Stop here if ownership or mode differs. Do not run generic chmod or chown, and do not disable SIP from a copied repair recipe. An incorrect change can damage macOS or other software, and there is no supported generic rollback established for these edits. Have the responsible macOS administrator correct the originating baseline, or escalate the recorded evidence to Apple or Sophos Support.

Distinguish installation, registration and configuration

The installer shows three separate states:

  1. Software Installed: local components were created.
  2. Registration Status to Sophos Central: the agent registered with the tenant.
  3. Configuration Status: policies and tenant configuration were received.

Closing the window does not stop registration or configuration download. A local installation does not prove registration, and registration does not prove complete configuration. Assign the error and displayed server to a stage before reinstalling.

The Mac does not appear in Sophos Fusion

Check in this order:

  1. Did the installer and tenant information come from the correct Sophos Fusion account?
  2. Are the Mac’s date, time and time zone correct?
  3. Do DNS and HTTPS access work without a captive portal?
  4. Does the intended proxy allow the current Sophos destinations, and are proxy credentials and root certificates valid?
  5. Under Management Communication, does Endpoint Self Help show a server, resolved address, expected proxy and recent successful contact?

Invalid Server URL indicates failed name resolution. HTTP 503 instead tells the client to retry later. If registration succeeds but configuration does not, inspect Management Communication and last policy receipt rather than rerunning the installer; the installation guide explains policy timestamps, the System page and process roles in detail.

Triage permissions and MDM

Open Sophos Endpoint > About > Open Endpoint Self Help Tool > Prerequisites. Self Help is authoritative because required Security Extensions, Network Extensions and privacy approvals depend on agent version and installed products. After correction, Prerequisites must show no missing approval.

For one Mac, follow the Open System Settings or Allow Full Disk Access workflow offered by Self Help. For read-only TCC and MDM payload diagnosis, use the dedicated CLI and permissions guide; do not edit TCC databases or profiles manually. On managed Macs, profile selection, payloads and deployment order belong in the MDM rollout guide.

Narrow update errors with available signals

Do not combine two different Updater conditions:

  • On macOS 14 and 15, missing Full Disk Access for SophosUpdater can block updates on Endpoint versions before 2024.3 (10.9.1).
  • Since Endpoint 2024.4 (10.9.5), the same missing permission can proactively turn Sophos Updater service health red even when no update has failed. A red state alone therefore does not prove a current update failure.

Check Prerequisites first. For the first condition, this read-only log check is a supporting diagnostic signal:

sudo log show \
  --predicate "subsystem == 'com.sophos.macendpoint'" \
  --last 1d |
grep -i 'Error renaming Installer directory'

A match supports this specific permission diagnosis but does not prove every update cause. For the before 2024.3 (10.9.1) condition without MDM, manually enable SophosUpdater.app under System Settings > Privacy & Security > Full Disk Access; if it is absent, add /Library/Sophos Anti-Virus/SophosUpdater.app with the plus button. For preventive red health on 2024.4 (10.9.5) and later, use Endpoint Self Help > Prerequisites > Allow Full Disk Access instead, because the normal picker may not show an Updater that macOS has not blocked. With MDM, deploy the current matching Sophos profile for the installed components in either case. The complete remediation and validation are in the CLI and permissions guide. This is not a general agent repair command or an update rollback.

If Sophos Fusion reports error 6001 while downloading MacEndpoint and SophosUpdater.log also contains 403 Forbidden or EXPIRED_TOKEN, check DNS, proxy and MCS communication: the Mac could not renew its token. HTTP 503 means the service asked the client to retry later. Escalate a service still shown as missing under Services with the component name and SDU instead of deleting agent files.

Legacy only: /Library/Preferences/Logging failure

This branch applies only to macOS Ventura 13.6.3 or Sonoma 14.2 with Sophos Endpoint before 2024.1. After an installation failure, this read-only check can show the permission error at /Library/Preferences/Logging:

sudo log show --predicate "subsystem == 'com.sophos.macendpoint'" --last 2h | grep -i Logging

Only for that exact combination and a matching result, use the former bounded procedure: allow Sophos Installer under System Settings > Privacy & Security > Full Disk Access, also allow Terminal if needed for an installation run from Terminal, and rerun the installation. Endpoint 2024.1 and later contains the fix; current versions must not use this legacy workaround. Remove Terminal access granted only for diagnosis afterwards.

Retry in a controlled manner

  1. Correct one confirmed cause and record the change.
  2. Recheck Self Help, network or path permissions as applicable.
  3. For trust or tenant problems, use a freshly downloaded installer from the correct tenant.
  4. Run one new installation attempt and follow all three status stages to the result.
  5. Do not delete agent files or the Sophos Fusion device object as a retry action.

If the device object was already deleted from Sophos Fusion and the existing installation therefore cannot re-register, do not attempt an undocumented manual re-registration. Only for this scenario, the supported path for Endpoint 2024.1 and later is a complete removal and reinstall. Follow Uninstall Sophos Central Endpoint on macOS, including Tamper Protection and validation. For other inconsistent states, diagnose the specific symptom and escalate to Sophos Support if needed instead of removing the product by default.

Validate and escalate with useful evidence

The workflow succeeds only when:

  • Prerequisites shows no missing local permission,
  • the Mac appears in the correct tenant under My Environment > Computers & Servers with current Sophos Fusion communication,
  • expected products and policies are active on the device details page,
  • Update and Management Communication in Self Help show successful contact again.

If the error remains, preserve the exact message, timestamp, three installer states, macOS and agent versions, affected path or component, Self Help observations, Sophos Fusion events, and proxy or MDM status. Create an SDU through the existing Sophos diagnostics/support workflow and state when the error was reproduced. Do not manually alter the generated SDU archive. Send it only through the approved Sophos Support case or upload channel and never publish it. Where practical, redact only separate screenshots or accompanying notes, and never add credentials to those items or case notes.