Troubleshooting
Fix a standalone DefenseClaw enterprise deployment by lifecycle error code, MDM wrapper code, hook refusal code, or symptom, on Windows, Linux, and macOS.
Start with the result document of the action that failed. Every lifecycle
action prints one when you pass --json (JSON=1 for the Windows Setup), and
the MDM wrapper scripts always print one. Find the stable machine code in errors[].code and look
it up below. The message next to it has the details. To produce a fresh
document, run verify (see Status and verify).
Exit codes
| Meaning | Linux and macOS | Windows standalone | What to do |
|---|---|---|---|
| Success, or nothing to change | 0 | 0 | Nothing |
| The action failed. A mutating action has already rolled back | 1 | 1603 | Read errors[].code |
| Invalid arguments | 2 | 1639 | Fix the command line or MDM settings. Retrying does not help |
| Another lifecycle run holds the lock | 75 | 1618 | Retry later |
A standard account ran an action that needs elevation (elevation_required) | — | 5 | Run it from an elevated prompt |
| Reserved: success, reboot required | — | 3010 | Not used today |
The Secure Client profile on Windows returns only 0 and 1603.
On Windows, the standalone Setup can also refuse before the lifecycle
starts. A malformed command line exits 1639: a relative or
environment-expanded CONFIG= or MANIFEST= path, an unknown property,
/install without CONFIG= and MANIFEST=, or TIMEOUTSECONDS out of
range. Other refusals before the lifecycle starts, such as a token that is
not elevated, exit 1603. With JSON=1 Setup then prints a short document
with an error string and no errors[].code.
Lifecycle error codes
These codes come from the lifecycle itself. The OS column says where each one can appear.
| Code | OS | Meaning | Fix |
|---|---|---|---|
unsupported_platform | Linux, macOS | The Linux or macOS lifecycle ran on another OS | Run the lifecycle for this OS |
invalid_arguments | all | The command line is wrong: conflicting flags, a relative --config, install or upgrade without --payload or --from-package, a first Windows ensure without a config, or a Windows ensure that must upgrade but was not given the payload files | Correct the command. On Windows, run the Setup, which supplies every payload file. Exit 2 or 1639 |
lifecycle_busy | all | Another lifecycle run holds the lock. On Linux and macOS the message says how long this run waited | Wait for it to finish and rerun. On Linux and macOS, a longer --lock-wait <duration> (at most 15m) waits for it instead (verify has no --lock-wait). Exit 75 or 1618 |
not_root | Linux, macOS | The action needs root. status reports it too when a standard user cannot read the deployment record | Run it with sudo or from the MDM agent |
service_manager_unavailable | Linux | systemd is not the init system (containers, WSL), or it is older than 239 | Use a supported host. See Requirements |
wsl_distribution | Linux | The host is a WSL distribution. A new install is refused; an existing deployment gets this as a warning | Uninstall it and govern WSL from Windows. See Agent sessions in WSL |
state_unreadable | Linux, macOS | The lifecycle state (/var/lib/defenseclaw-enterprise on Linux, /opt/cisco/defenseclaw/lifecycle on macOS) cannot be read | Check that directory and the disk |
already_installed | Linux, macOS | install ran on a host that already has a deployment | Use ensure, upgrade, or repair |
not_installed | all | upgrade, repair, reconcile, or verify found no deployment. On Windows, also an install, upgrade or ensure that reported success but left no deployment | Install first. ensure installs when nothing is there. On Windows, run the same command again; if it repeats, keep the lifecycle log for support |
profile_conflict | all | A Cisco Secure Client DefenseClaw deployment is present. The two profiles cannot run on one host. On Windows, --profile secure_client on a standalone computer is refused the same way, with exit 1639 | Uninstall the Secure Client deployment first; on a standalone computer use --profile standalone or omit --profile |
unmanaged_layout_present | Linux, macOS | DefenseClaw files or units exist that no committed deployment owns, for example from a hand-made install | Rerun install or ensure with --adopt-existing. It backs up that layout and takes it over |
payload_invalid | Linux, macOS | The payload is missing a binary, is not owned by root, is writable by group or others, is a symlink, or is not the --product-version you asked for. repair also reports this when the installed binaries no longer match the deployment record | Stage the payload again as root. For repair, pass --payload with the installed release |
package_owned_binaries | Linux | A --payload upgrade on a host where the deb or rpm owns the binaries | Upgrade with the package manager |
config_invalid | Linux, macOS | The --config file does not exist, is a symlink, or another account could change it (owner, mode or folder), or the config failed validation. It needs config_version: 8 and the fixed data_dir. deployment_mode and enterprise.profile must be managed_enterprise and standalone if you set them, and gateway.api_bind and gateway.api_port must be 127.0.0.1 and 18970 if you set them. The message names the file, the line, the field and the fix, for example line 34: guardrail.mode is "blockall"; allowed values: observe, action, or a protected credential enterprise secret set has not stored. On Windows an invalid config fails under another code (for example manifest_staging_failed or lifecycle_error); read errors[].message | Fix the file or pass the real, root-owned path; the message names the step. See the settings reference |
service_account | Linux, macOS | Creating or checking the gateway service account (defenseclaw or _defenseclaw) failed | Check useradd or dscl and your directory service |
apply_failed | Linux, macOS | Writing the files failed. The action rolled back | Read the message. Check disk space and read-only mounts |
activation_failed | Linux, macOS | A service did not start or did not become ready. The action rolled back | Read the gateway output excerpt in the message and last-activation-failure.log in the lifecycle directory, then the service logs. See Logs and events |
verify_failed | Linux, macOS | In status and verify: one error per problem found (status runs fewer checks). In a mutating action: the check after applying failed, and the action rolled back | Read each message. Most are fixed by ensure or repair |
rollback_failed | Linux, macOS | A failed action could not restore the previous deployment completely | Run repair or ensure. If it still fails, save the result and the logs, then uninstall and install again |
machine_policy_failed | Linux, macOS | The enterprise.machine_policy settings are invalid, or a vendor policy file could not be read or written | Check those settings and the file named in the message. See Machine policy |
uninstall_failed | Linux, macOS | Some files, directories, or the service account could not be removed | Read the message and run uninstall again |
per_user_hooks_remaining | Linux, macOS | Uninstall could not remove a user's DefenseClaw hook registrations for an agent; there is one error per user and agent, with the reason. (When the cause is only that the user's home is not available, the same code is a warning instead and the uninstall goes on; see Warnings.) The uninstall then stops before it removes the binaries those registrations run, and keeps the deployment record and state | Fix the cause, or remove DefenseClaw's entries from that user's agent config, and run the same uninstall again. ensure restores the deployment instead |
reconcile_failed | Linux, macOS | The immediate guardian reconcile failed. When the guardian could not protect a target, there is one error per target, in the words of its guardian_target_failed or hook_contract_unverified warning. A target of a deleted account (guardian_target_account_removed) or one refused for a path in the account's own home (guardian_target_user_path) stays a warning | Read each message. If it does not name a target, read the guardian log |
downgrade_refused | all | The payload or package is older than the installed release. On Windows, ensure found a newer release installed than the Setup you ran | To go back on purpose, see Roll back (--allow-downgrade on Linux and macOS) |
config_rejected | Linux, macOS | status warns and verify fails: the run that applied an in-place edit of config.yaml failed, the last applied config was put back, and the edit is kept as rejected-config.yaml in the lifecycle directory. The run's result in the lifecycle log says whether the file or something else, such as a service that did not start, failed | Fix what the lifecycle log names. Then write config.yaml again, even unchanged, to retry, or push a corrected config or the previous one. See Change the config |
powershell7_required | Windows | PowerShell 7 (the x64 MSI) is not installed under Program Files | Install PowerShell 7 x64 |
powershell7_untrusted | Windows | pwsh.exe is not a regular file, is writable by non-administrators, or is not signed by Microsoft | Reinstall PowerShell 7 from the Microsoft MSI |
powershell_32bit_host, powershell_constrained_language | Windows | The lifecycle was started in 32-bit PowerShell or in Constrained Language mode | Start it from a 64-bit process in Full Language mode, or use the MDM wrapper |
unsupported_architecture | Windows | The host is not native x64. x64 emulation on ARM64 is refused | Use an x64 device |
ensure_refused | Windows | ensure could not choose an action, for example because it could not read the installed deployment's metadata | Read the message, then run repair |
manifest_staging_failed | Windows | ensure could not prepare the first target manifest from the config | Check the config |
lifecycle_launch_failed | Windows | The PowerShell 7 lifecycle did not start, or it printed no result | Read the message and enterprise-lifecycle.log |
lifecycle_error | Windows | The lifecycle reported a failure without a stable code | Read errors[].message and enterprise-lifecycle.log |
rule_pack_unreadable | Windows | The gateway service account (NT SERVICE\DefenseClawGateway) cannot read the folder guardrail.rule_pack_dir names. The message gives the icacls command that grants it; the enumerator's full output is in the lifecycle_diagnostic warning | Grant the service Read & execute on the folder, then run Setup again |
not_ready | Windows | The run finished, but the deployment is not healthy. The message names the stopped services | Start them with repair --profile standalone (or Setup /repair JSON=1) from an elevated prompt; otherwise run verify, then read the gateway and guardian logs |
gateway_start_failed | Windows | status or verify found the gateway service not running; the message gives the last error the service logged and the log path | Fix what the error names. If it says Access is denied, run repair from an elevated prompt |
api_port_held | Windows | The gateway service runs, but another process listens on 127.0.0.1:18970 or on the wildcard address of that port, so the gateway cannot bind its API and hooks fail closed. An install, upgrade or repair whose gateway never became ready reports it too. The message and api_port_holders[] name each process's PID, image and account, or say that this account cannot identify it | Stop that process. The gateway keeps retrying and takes the port back by itself, without a restart; after a failed install, run the install again |
elevation_required | Windows | A standard account ran enterprise windows status, verify, repair, upgrade or ensure. Only an elevated prompt can run the installer's own checks or change the deployment; nothing was changed. Exit 5 | Run the command from an elevated PowerShell prompt |
preflight_failed | Windows | A check before the lifecycle started failed | Read the message |
change_failed | Linux, macOS | enterprise secret set or another protected-state change could not be written before ensure applied it | Read the message. Check that you ran it as root and that the secrets folder is writable by root |
rotation_failed | Linux, macOS | rotate-credentials did not commit the new key. The message names the step and the users; the previous key stays in use. When it ends with "nothing was changed", the check before the rotation failed | Fix what the message names (often a user the guardian protected before and cannot protect now), then rotate again. See Rotate per-user credentials |
Warnings
Warnings do not fail an action. They appear in warnings[].
| Code | OS | Meaning |
|---|---|---|
rolled_back | Linux, macOS | A failed action restored the previous deployment. The error beside it says why |
recovered_interrupted_transaction | Linux, macOS | This run found an interrupted run and rolled it back first |
rotation_recovered | Linux, macOS | This run found an interrupted rotate-credentials and completed it (the new key had replaced the old one) or rolled it back |
rotation_incomplete | Linux, macOS | status or verify found a rotate-credentials run that did not finish. Run rotate-credentials again, or any other mutating action, to complete it or roll it back |
recovered_failed_install | Windows | This run rolled back a failed first install |
rollback_leftover | Windows | The rollback of a failed first install could not remove one item. The message names it (by account and connector for an account's agent configuration) and what removes it: run Setup /ensure and then /uninstall, both as LocalSystem while the accounts are signed in (from an elevated prompt, through a one-time scheduled task that runs as SYSTEM; see Run Setup as LocalSystem), or, for a file the account changed after DefenseClaw wrote it, remove DefenseClaw's entries from that file by hand. A signed-out account keeps DefenseClaw's entries until then. Setup run from an elevated prompt is not LocalSystem, so it leaves every account's registrations ("because Setup did not run as LocalSystem"); only that run's result lists them |
security_incomplete | Windows | security_complete is false and nothing else in the result says why. The message lists the reasons. "The claudecode machine policy is not verified in force" usually means the Claude Code attestation is missing, or is stale after an upgrade. Complete the attestation in Verify the install: confirm that an enrolled user's Claude Code runs DefenseClaw's hooks, then run Setup /repair ATTESTCLAUDEEFFECTIVEPOLICY=1 |
machine_policy_incomplete | Linux, macOS | DefenseClaw's hooks are not in place in a vendor policy file for the named connectors, for example because a higher-precedence source outranks it. verify also fails with verify_failed |
claude_version_floor_missing | Linux, macOS | DefenseClaw's Claude Code version floor drop-in (00-defenseclaw-version-floor.json) is missing. The hooks are still in place and verify still passes. The next ensure, repair or reconcile writes it back. See Claude Code version floor for the builds it applies to |
not_started | Linux, macOS | Installed with --no-start. Run repair or ensure to start the services |
adopted_existing_layout | Linux, macOS | --adopt-existing backed up the old layout to the lifecycle directory |
selinux_relabel | Linux | restorecon failed after the files were written |
ai_defense_unavailable | Linux, macOS | Cisco AI Defense is enabled, but the gateway reports inspection.ai_defense as unavailable:<code> (for example auth_failed or credential_unavailable). The local policy engine keeps deciding. Check the credential enterprise.inspection.ai_defense.credential names and the network path; see Check the key |
per_user_hooks_remaining | Linux, macOS | A user's home was not available, so uninstall could not remove that user's hook registrations for the named agent, and went on without them. Once the home is available, remove DefenseClaw's entries from that agent's config. Any other reason a removal fails is an error that stops the uninstall; see Lifecycle error codes |
per_user_state_remaining | Linux, macOS, Windows | uninstall --purge (Setup PURGE=1 on Windows) could not remove a user's DefenseClaw folder (~/.defenseclaw, or %USERPROFILE%\.defenseclaw on Windows); the message gives the reason. On Windows a purge that did not run as LocalSystem removes the machine deployment but no account's data, so it is an error (non-zero exit) that names the accounts. Remove what stays by running Setup /ensure and then /uninstall PURGE=1, both as LocalSystem while the accounts are signed in (see Run Setup as LocalSystem) |
machine_state_remaining | Windows | Setup /uninstall (with or without PURGE=1) or the MDM uninstall script could not remove a machine folder DefenseClaw created outside its state folder: an empty C:\Program Files\ClaudeCode\managed-settings.d or ClaudeCode, or a C:\ProgramData\DefenseClaw-PowerShell-<32 hex>, C:\ProgramData\DefenseClaw-Installer-<32 hex> or C:\Windows\Temp\DefenseClaw-Bootstrap-<32 hex> folder an interrupted elevated command left. The message gives each path and the reason. Remove them from an elevated prompt |
user_registrations_pending, user_registrations_failed | Windows | Uninstall could not act as some users (they had no active, connected session: signed out, or signed in with a disconnected session; or the uninstall did not run as LocalSystem; the warning says which), or a per-user removal failed. The warning lists each account with its connectors. What stays is inert. To remove it, run Setup /ensure and then /uninstall, both as LocalSystem while the accounts have an active (connected) session (reconnect a disconnected one first) |
package_install_failed | Linux, macOS | status or verify found no deployment, and the package's own install run (last-package-result.json in the lifecycle directory) failed. The message gives that run's first error, for example a protected credential that is not stored yet. Fix it, then run enterprise linux ensure --from-package. On macOS install the pkg again: that also records the pkg receipt, which enterprise macos ensure --from-package does not |
elevation_required | Windows | A standard account ran enterprise windows status, verify, repair, upgrade or ensure. Only an elevated prompt can run the installer's own checks or change the deployment; nothing was changed. Exit 5. Run the command from an elevated PowerShell prompt |
health_not_checked | Windows | The request was refused before any health check ran (a standard account's status or verify, or an unknown --profile). The result reports only the recorded deployment and the service states: readiness.enumerator and readiness.sensor_helper follow the service states, while readiness.gateway, readiness.guardian, coverage_complete and security_complete read false because they were not checked. A standard account cannot read the recorded version, so installed_version is omitted. For the deployment's health, run enterprise windows verify --json from an elevated PowerShell prompt |
deleted_account_rows | Windows | A local account was deleted but its profile folder is still there, so DefenseClaw keeps its enrollment rows. Remove the profile (System Properties > Advanced > User Profiles) to revoke them. Once the profile is removed, the enumerator drops the rows at its next pass; until then the guardian's failures for that account are reported here and status and verify stay healthy. Domain and Microsoft Entra accounts are not checked, because their lookup also fails while the directory cannot be reached |
enrollment_pending_account_folder | Windows | An account created its own %USERPROFILE%\.defenseclaw, for example when an agent it ran before enrollment was refused, or after it moved DefenseClaw's folder away. DefenseClaw takes over the folder when the account next signs in; repair leaves it alone until then |
hook_contract_unverified | all | A user runs an agent version that has no verified DefenseClaw hook contract, so that agent runs without DefenseClaw hooks. security_complete is false; verify warns for that account and does not fail |
agent_unprotected | all | The enumerator found an agent installed for a user but could not enroll it; the message gives the reason. security_complete is false; verify warns for that account and does not fail. See Enrollment |
guardian_target_failed | Linux, macOS | The guardian could not install or repair hooks for one user and connector; the message gives the reason. Every other user stays protected. If the message says the guardian state does not say why, the guardian's root-only attestation reports the failure but the state file in the data directory does not; read the guardian log |
guardian_target_user_path | Linux, macOS | The guardian could not protect one user and connector because of a path in that user's own home: a link, a file where a folder belongs (or a folder where a file belongs), or a folder the user made unreadable. The message names the path. Only that user is affected, and the guardian protects the account again at its next reconcile after the path is fixed. This is a warning only: reconcile, verify, detect.sh --require-healthy and security_complete do not fail on it. See When a user breaks their own setup |
guardian_target_account_removed | Linux, macOS | A target's account no longer exists (the directory answers "no such account"), usually because it was deleted. DefenseClaw reports it only when the guardian's error is exactly that answer and the host's own account lookup also finds no such account. The enumerator removes the target after three consecutive definitive misses, one per enumeration cycle, and enterprise linux repair or enterprise macos repair removes it at once. This is a warning only: verify, reconcile, detect.sh --require-healthy and security_complete do not fail on it. During a directory outage that also hides a directory account from lookups, the warning can appear for an account that still exists; it clears when the directory answers again |
guardian_cleanup_pending | Linux, macOS | A user is no longer enrolled for a connector (the connector was disabled or removed from the config, or the user was excluded), and the guardian has not yet removed DefenseClaw's hook registration from that user's home, so the gateway refuses those hooks. The guardian removes it as the user once the home is available and retries a failed removal; the message gives the last error. This is a warning only: verify and security_complete do not fail on it. See Enrollment |
enrolled_account_deleted | Linux, macOS | An account that targets.yaml still enrolls no longer has a home, because the account was deleted. Its enrollment lasts until the hook enumerator's next pass drops it, and enterprise hooks status shows the account as deleted instead of its agents as pending. Nothing is left to protect in that home. This is a warning only: verify and security_complete do not fail on it. |
guardian_user_file_pending | Linux, macOS | The guardian has not yet had its first pass for a newly enrolled user (right after an install, or for a user the enumerator just enrolled), so that user's DefenseClaw-owned per-user hook file (Copilot's VS Code Local hook file) is not written yet. The guardian writes it within a minute or two. This is a warning only: verify does not fail on it. Once the guardian has written the file, a missing or edited copy fails status and verify until the guardian rewrites it. A deleted account's file is not reported |
per_user_gateway_running | Linux, macOS | An account still runs its own per-user DefenseClaw gateway, started before the deployment, beside the managed one. It keeps its own config and policy. The computer refuses to start it again, so stop it with the kill command the message gives, and have that user remove the per-user install with defenseclaw uninstall --binaries --yes. The install, status and verify report it as a warning |
no_connectors_enabled | Linux, macOS | The config enables no agent under guardrail.connectors, but the enumerator found eligible users, so nobody is protected. security_complete is false. Add the agents to protect under guardrail.connectors and apply the config; see Choose the agents to protect |
unmanaged_leftovers | Linux, macOS | status or verify found DefenseClaw state with no deployment. Use uninstall --purge to remove it |
unit_failed | Linux, macOS | A DefenseClaw service or one-shot job failed on its last run (for example defenseclaw-enterprise-verify.service). The message names the unit and the log command; on Linux clear it with systemctl reset-failed <unit> once resolved |
input_changed | Linux, macOS | config.yaml or a protected credential changed while this run applied the previous version. A follow-up transaction in the same run applied it, or, after a failed run, the apply trigger runs ensure for it once this run ends |
config_reverted | Linux, macOS | An in-place edit of config.yaml was not applied; the last applied config was put back for the rollback and the rejected edit is kept as rejected-config.yaml. When a newer config.yaml was written during the run, that file is put back afterwards and applied next |
lifecycle_superseded | Linux, macOS | A queued apply run of an older binary found a newer release installed while it waited, and stood down; the installed binary applies later changes |
guardian_report_pending | Linux, macOS | After a change the guardian had not reported its targets within 30 seconds. Run status or verify a moment later |
package_installed, package_upgraded | Linux, macOS | In the MDM wrapper's result: the wrapper installed or upgraded the package (the message gives the versions) before the ensure whose result follows |
ensure_install, ensure_upgrade, ensure_repair | Windows | The action that ensure chose, and why |
registration_failed, lifecycle_log_failed | Windows | The registry marker, the Add/Remove Programs entry, or the lifecycle log could not be written. The result itself stands |
MDM wrapper error codes
The wrapper scripts in packaging/mdm check their inputs before they start
the lifecycle. Most codes that start with mdm_ mean the wrapper stopped
before the lifecycle ran. mdm_not_installed after an apply, and
mdm_secret_failed on Windows, are reported after the lifecycle succeeded. In every mdm_
document, installed: false means "not checked". They use the exit
codes above. For the full contract, see Exit codes.
| Code | Meaning |
|---|---|
mdm_invalid_arguments | A flag or setting is missing, malformed, or conflicts with another. On Linux and macOS, any unknown or positional argument also exits 2 with this code |
mdm_not_root, mdm_not_elevated | Not running as root, SYSTEM, or an elevated administrator |
mdm_wrong_platform | The Linux copy ran on macOS, or the reverse |
mdm_hash_mismatch | The staged source does not match the pinned SHA-256 |
mdm_signature_invalid, mdm_signer_not_allowed, mdm_signature_unsupported | Signature trust failed, the signer is not allowed, or this source type cannot be checked by signature |
mdm_version_mismatch | Linux and macOS: the source is not the --product-version you set |
mdm_untrusted_input | A config, credential, or keyring file can be changed by a non-administrator, or (uninstall.sh) the installed gateway is not root-owned |
mdm_untrusted_install | Windows, uninstall.ps1: the installed CLI or its folders are not administrator-only |
mdm_input_too_large | The config is over 1 MiB or the credential is over 16 KiB |
mdm_payload_invalid, mdm_package_invalid, mdm_wrong_package, mdm_wrong_architecture | Linux and macOS: the archive or package is not a DefenseClaw enterprise artifact for this host |
mdm_package_manager_busy | Linux and macOS: dpkg, rpm, or the installer held its lock. Exit 75; retry |
mdm_package_install_failed, mdm_package_remove_failed, mdm_package_manager_missing | Linux and macOS: the package manager failed or is missing |
mdm_download_failed, mdm_download_unavailable | Linux and macOS: the HTTPS download failed, or there is no curl or wget |
mdm_not_installed | A read-only action, or an ensure without a source, found no deployment |
mdm_lifecycle_no_result, mdm_lifecycle_launch_failed | The lifecycle did not start or printed no result |
mdm_secret_failed | Storing the credential failed: on Windows after the deployment applied; on Linux and macOS before the config was applied |
mdm_staging_untrusted, mdm_package_incomplete | The private staging folder or the Intune content is not as expected |
Wrapper logs: /var/log/defenseclaw-enterprise-mdm.log on Linux,
/Library/Logs/Cisco/DefenseClaw/mdm-wrapper.log on macOS, and
%WINDIR%\Logs\DefenseClaw\mdm-wrapper.log on Windows.
Hook refusal codes
An agent reports these codes in its hook output when DefenseClaw refuses a hook call.
| Code | OS | Meaning and fix |
|---|---|---|
enterprise_managed_uid_unregistered | Linux, macOS | The user is not enrolled for this connector. With unenrolled_users: deny, this also applies to machine-policy connectors. Fix: Enroll the user, then allow one enumerator cycle and a guardian reconcile. See A user is not enrolled |
enterprise_managed_sid_unregistered | Windows | The user's SID has no enrolled runtime. Fix: Enroll the user. The guardian writes the user's runtime only while the user is signed in |
enterprise_managed_enrollment_pending | Windows (standalone) | The user is enrolled but has not signed in to Windows since, so the guardian has not written their runtime yet (for example an account used only through runas or a scheduled task). Fix: Sign in to Windows once as that user |
enterprise_managed_root_denied | Linux, macOS | root called a hook while enrollment.root is deny. Fix: Run the agent as a normal user, or change enrollment.root |
enterprise_managed_ledger_unavailable | Linux, macOS | The gateway cannot read the guardian's authorization ledger. Fix: Check that the guardian is running, then run reconcile |
enterprise_managed_connector_unknown | Linux, macOS | The hook call named no connector the gateway recognizes. Fix: Check the hook registration; run reconcile |
enterprise_managed_peer_unverified | Linux, macOS | The gateway could not read the calling process's identity from the kernel. Fix: Run repair. If the code persists, save the gateway log and the result of verify |
enterprise_managed_gateway_peer_unverified | all | The hook could not verify the listener before it sent anything. Windows: the process listening on 127.0.0.1:18970 is not the running DefenseClawGateway service. Linux and macOS: the hook socket is not owned by root or the gateway account. Fix: Check status. On Windows, find the process that listens on port 18970; on Linux and macOS, run repair |
enterprise_managed_runtime_descriptor_missing | Linux, macOS | The runtime descriptor (managed-runtime.json) is missing. Fix: Run repair |
enterprise_managed_runtime_state_invalid | all | The hook's trusted runtime state is missing or invalid. Fix: Run repair, then reconcile |
enterprise_managed_runtime_home_missing | all | The user's DefenseClaw runtime folder is missing. Fix: The guardian manages this folder. Run reconcile, then read the guardian log |
enterprise_managed_runtime_disable_sentinel_forbidden | all | A .disabled file is in the user's DefenseClaw runtime folder. Managed hooks do not treat it as "off", so they refuse the call. Fix: Remove the file |
enterprise_foreign_hook_blocked | all | A user or repository config adds a hook or plugin that your policy has not approved. Fix: Remove it, or add its digest to enterprise.machine_policy.connectors.<name>.allowed_hooks. See Foreign-hook guard |
enterprise_foreign_hook_check_failed | Linux, macOS | Hermes only: DefenseClaw's Hermes hook got no usable answer from the foreign-hook check it runs through defenseclaw-hook, so it blocked the tool call. Fix: Check that defenseclaw-hook is installed and runs for the user; read ~/.defenseclaw/logs/hook-failures.jsonl; run repair |
enterprise_machine_policy_summary_untrusted | all | The machine policy summary the hook reads is not administrator-owned. Fix: Run repair |
enterprise_managed_rate_limited | all | HTTP 429: this account sent more hook requests than its budget allows (60 a second, a burst of 120, 32 at a time; OTLP export has its own budget). Of the 32, an account runs at most half as many at once as the gateway has processors (at least one); the rest wait their turn (a request waiting on Cisco AI Defense or the LLM judge gives its turn up meanwhile), so the other accounts keep the other half. Other accounts are not refused. The hook treats it as a gateway failure, and a managed hook always fails closed, so the call is blocked whatever hook_fail_mode says. Fix: Find what floods the gateway from that account (a loop, many parallel agents). The budget refills within a second |
Symptoms
| Symptom | Likely cause | What to do |
|---|---|---|
| An agent is not protected at all | Its connector is not a key under guardrail.connectors; for a per-user agent, enabled: false has the same effect. When no agent is enabled at all, status and verify warn no_connectors_enabled. On Linux and macOS the config the lifecycle writes when you supply none lists no agents. (Codex, Claude Code, Cursor and Copilot get machine policy whenever they are named under guardrail.connectors or enterprise.machine_policy.connectors.) | Add the connector under guardrail.connectors and apply the config. See Choose the agents to protect |
| An agent is not protected on one OS | Its route on that OS is unsupported. OpenClaw and ZeptoClaw are unsupported everywhere. OpenHands and OmniGent are unsupported on Windows | Use a supported agent on that OS. See Machine policy |
| A user is not enrolled (Linux) | A local account's uid is outside UID_MIN to UID_MAX from /etc/login.defs (1000 to 60000 if unset), or any account is above uid_max when you set it. Directory accounts have no upper bound unless you set uid_max | Add the user to enterprise.enrollment.include_users, which bypasses the uid range and the shell check, or change uid_min or uid_max |
| A user is not enrolled (Linux, macOS) | The login shell is nologin or false; the user is in exclude_users or an excluded group; the user is in exempt_users, which is inspected without enrollment; the home is outside the allowed home roots (/home and /var/home on Linux, /Users on macOS, plus home_roots) | Fix the account, the lists, or home_roots. See Enrollment |
| A user is not enrolled (macOS) | The uid is below 501 | Add the user to include_users or set uid_min |
| A user is not enrolled (Windows) | The user is in exclude_users or an excluded group; the user is in exempt_users, which keeps only the machine-policy agents; include_groups is set and the user is not a member, or their membership is still unknown (a directory user who has not signed in since installation stays pending); or the user is signed out or disconnected. The guardian writes hooks only during an active session | Have the user sign in, or change the lists. See Enrollment |
| A new user is protected only after a few minutes | The enumerator runs every 5 minutes | Wait one cycle. Run reconcile to apply existing rows at once |
security_complete is false on Windows | Claude Code is enabled and the Claude Code attestation is not recorded, or no Codex, Claude Code, or Cursor row is enabled in the target manifest | See Health fields |
security_complete is false on Linux or macOS | The sensor helper is not running, the run had errors, an agent is reported as agent_unprotected or hook_contract_unverified, a user target is reported as guardian_target_failed, or the config enables no agent for the eligible users (no_connectors_enabled) | Run verify and read the errors and warnings |
verify and detect.sh --require-healthy fail because of one user (guardian_target_failed) | Something in that user's account that the guardian cannot repair, for example a config the agent cannot parse or a folder another account owns, leaves the account unprotected. A link, a non-directory or an unreadable folder in the user's own home is reported as guardian_target_user_path instead and does not fail verify | Read the warning for the user and connector, and have the account fixed. See When a user breaks their own setup |
verify fails with verify_failed, and warnings[] has machine_policy_incomplete | A higher-precedence policy source outranks DefenseClaw's entry, or your own policy sets a conflicting value | See Machine policy. enterprise policy show names the source |
| AI Defense is not used | The credential is missing or unreadable, the credential name under enterprise.inspection.ai_defense does not match the stored credential, or the proxy blocks the connection. The local engine keeps deciding alone | Check enterprise secret status. The gateway logs an error from the cisco-inspect subsystem that starts with "standalone managed_enterprise: Cisco AI Defense disabled". Check enterprise.network.https_proxy, and restart the gateway after changing it. When AI Defense is enabled, the gateway's /health guardrail detail carries ai_defense_available, and ai_defense_error with the reason when it is false |
enterprise policy show or verify refuses for a standard account | The policy commands read the managed config, which only administrators can read. On Windows the message says to use an elevated prompt | Run it as root on Linux and macOS, or from an elevated prompt on Windows. See Machine policy status |
policy verify --live refuses | --live needs --user, one --connector (codex or claudecode), and --agent-binary. On a managed Windows host --live is not available at all | Add the missing flags. On Windows, use the static verify and confirm with audit export; see Inspect machine policy |
enterprise secret set fails on a new Windows host | On Windows it refuses until a standalone deployment is installed. On Linux and macOS it stores the key root-only and the install applies it | Install first, then store the key. See AI Defense key |
The per-user installer or defenseclaw upgrade refuses | The host has a managed deployment. The per-user install.ps1, defenseclaw upgrade, defenseclaw rollback, and a per-user gateway all refuse to run beside it | Update through your MDM. See Per-user installs |
The first managed install fails to start the gateway (activation_failed on Linux and macOS, not_ready on Windows) | A per-user DefenseClaw gateway, or another process, still listens on 127.0.0.1:18970 | Find the process with the port commands below. If it is a per-user DefenseClaw, have that user run defenseclaw uninstall --binaries --yes (defenseclaw uninstall --all --binaries --yes on Windows), then run ensure again. See Handle existing per-user installs |
Exit 1618 or 75 | Another lifecycle run holds the lock | Retry. Intune retries 1618 by default |
Exit 1639 or 2 | Invalid arguments | Fix the command line or MDM settings. Retrying does not help |
| A Linux package installed, but nothing runs | The package's install script never fails the package transaction. After a package downgrade the lifecycle refuses with downgrade_refused | Read /var/lib/defenseclaw-enterprise/last-package-result.json. For a deliberate downgrade, see Roll back |
| A macOS pkg install failed | The lifecycle failed and rolled back, and the install script failed the installation. An older package is refused before any file changes unless the rollback marker exists | Read /opt/cisco/defenseclaw/lifecycle/last-package-result.json and last-activation-failure.log in the same folder. For a deliberate downgrade, see Roll back |
systemctl start defenseclaw-hook-guardian.service has no effect | The guardian is always running | Run enterprise linux reconcile, or start defenseclaw-hook-guardian-reconcile.service |
Find what holds port 18970
sudo ss -ltnp 'sport = :18970'sudo lsof -nP -iTCP:18970 -sTCP:LISTENGet-NetTCPConnection -LocalPort 18970 -State Listen | Select-Object LocalAddress, OwningProcessUpgrade, repair and remove
Upgrade, roll back, change the config, repair, and uninstall a standalone DefenseClaw enterprise deployment on Windows, Linux, and macOS, with a decommission checklist.
Reference
Lookup tables for the DefenseClaw CLI, the sidecar API, configuration files, credentials, fail modes, and environment variables.