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

MeaningLinux and macOSWindows standaloneWhat to do
Success, or nothing to change00Nothing
The action failed. A mutating action has already rolled back11603Read errors[].code
Invalid arguments21639Fix the command line or MDM settings. Retrying does not help
Another lifecycle run holds the lock751618Retry later
A standard account ran an action that needs elevation (elevation_required)—5Run it from an elevated prompt
Reserved: success, reboot required—3010Not used

The Secure Client profile on Windows returns only 0 and 1603. The standalone Setup can also refuse before the lifecycle starts. It exits 1639 for a malformed command line (a relative or environment-expanded CONFIG= or MANIFEST= path, an unknown property, /install without CONFIG= and MANIFEST=, or TIMEOUTSECONDS out of range) and for a config or manifest file that a non-administrator can change. A token that is not elevated exits 1603. With JSON=1 the standalone Setup prints the same schema-version-2 document as the lifecycle, with invalid_arguments in errors[].code. On Windows, an option defenseclaw.exe does not know (a misspelled flag) on a lifecycle verb also exits 1639, with unknown flag (1.0.4 and earlier exit 1); fix the command line.

Lifecycle error codes

These codes come from the lifecycle itself. The OS column says where each one can appear.

CodeOSMeaningFix
unsupported_platformLinux, macOSThe Linux or macOS lifecycle ran on another OSRun the lifecycle for this OS
invalid_argumentsallThe 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 filesCorrect the command. On Windows, run the Setup, which supplies every payload file. Exit 2 or 1639
lifecycle_busyallAnother lifecycle run holds the lock. On Linux and macOS the message says how long this run waited, and status reports it as a warning with ok: true and pending_apply: true (a change is being applied, not a failure). On Windows, also a Setup upgrade of the installed release on processors less than 25% idle: it stops before changing anything, because it could not finish within TIMEOUTSECONDSWait 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
bundle_not_appliedWindowsA signed policy bundle is confirmed but does not enforce: config.yaml is not the bundle's config (it was changed outside the lifecycle or deleted), the bundle store cannot render it, or the running gateway reports another effective policy or a rejected reload. status and verify fail on it, so Remediate-Detect.ps1 is not compliantRun ensure (the Intune remediation does): it re-applies the confirmed bundle from the bundle store. Exit 1603
bundle_restore_failedWindowsensure or repair could not put the confirmed bundle's config back over an edited or deleted config.yaml: the bundle store or its version directory cannot be read, config.yaml cannot be read, or the write failed. The run also reports bundle_not_applied. Nothing was started on the edited fileDeliver the bundle again, or a newer one. Exit 1603
not_rootLinux, macOSThe action needs root. status reports it too when a standard user cannot read the deployment recordRun it with sudo or from the MDM agent
service_manager_unavailableLinuxsystemd is not the init system (containers, WSL), or it is older than 239Use a supported host. See Requirements
wsl_distributionLinuxThe host is a WSL distribution. A new install is refused; an existing deployment gets this as a warningUninstall it and govern WSL from Windows. See Agent sessions in WSL
state_unreadableLinux, macOSThe lifecycle state (/var/lib/defenseclaw-enterprise on Linux, /opt/cisco/defenseclaw/lifecycle on macOS) cannot be readCheck that directory and the disk
already_installedLinux, macOSinstall ran on a host that already has a deploymentUse ensure, upgrade, or repair
not_installedallupgrade, repair, reconcile, or verify found no deployment. On Windows, also an install, upgrade or ensure that reported success but left no deploymentInstall first. ensure installs when nothing is there. On Windows, run the same command again; if it repeats, keep the lifecycle log for support
profile_conflictallA 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 1639Uninstall the Secure Client deployment first; on a standalone computer use --profile standalone or omit --profile
unmanaged_layout_presentLinux, macOSDefenseClaw files or units exist that no committed deployment owns, for example from a hand-made installRerun install or ensure with --adopt-existing. It backs up that layout and takes it over. On a Linux tarball host with fapolicyd, follow the two-stage install flow, passing --adopt-existing to the staged ensure
payload_invalidLinux, macOSThe 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 recordStage the payload again as root. For repair, pass --payload with the installed release; on a Linux tarball host with fapolicyd, use the two-stage trust flow before starting services. When a package binary was replaced, reinstall the package of the installed version (the message names the command)
package_owned_binariesLinuxA --payload upgrade on a host where the deb or rpm owns the binariesUpgrade with the package manager
config_invalidLinux, macOSThe --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: 9, or 8, which ensure migrates to 9, and the fixed data_dir. If you set them, deployment_mode and enterprise.profile must be managed_enterprise and standalone, and gateway.api_bind and gateway.api_port must be 127.0.0.1 and 18970. 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. It is also reported when the installed config.yaml changed while an account other than root could write it; that change is not applied and the last applied config is put back (config_reverted). On Windows an invalid config fails under another code (for example manifest_staging_failed or lifecycle_error); read errors[].messageFix the file or pass the real, root-owned path; the message names the step. See the settings reference
service_accountLinux, macOSCreating or checking the gateway service account (defenseclaw or _defenseclaw) failedCheck useradd or dscl and your directory service
apply_failedLinux, macOSWriting the files failed. The action rolled backRead the message. Check disk space and read-only mounts
api_port_heldLinux, macOSBefore changing anything, an install, ensure, upgrade or repair found another process, usually a per-user DefenseClaw gateway, listening on the gateway API port 127.0.0.1:18970. Nothing was changedStop the process with the kill command the message gives, or move it to another port, then run the command again. See Find what holds port 18970
activation_failedLinux, macOSA service did not start or did not become ready. The action rolled backRead the gateway output excerpt in the message and last-activation-failure.log in the lifecycle directory, then the service logs. See Logs and events
config_refusedLinux, macOSstatus, verify or a failed upgrade, repair or ensure: the gateway does not start because the installed gateway binary refuses the installed config, for example a custom rule pack whose files no longer match guardrail.custom_packs.<name>.digest. The message gives the refusal. repair fails the same wayCorrect the setting the message names, in config.yaml or in the file you pass to ensure --config, and run ensure
verify_failedLinux, macOSIn 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 backRead each message. Most are fixed by ensure or repair
rollback_failedLinux, macOSA failed action could not restore the previous deployment completelyRun repair or ensure. If it still fails, save the result and the logs, then uninstall and install again
disk_fullLinux, macOS; Windows policy bundlesA failed install, ensure, upgrade or repair ran out of disk space. It follows the error of the step that failed (for example verify_failed or apply_failed) and names the path a write failed on or each filesystem DefenseClaw writes that had less than 16 MiB free. The action rolled back, or changed nothing when it ran out of space before it started. Applying a bundle or installing a trust anchor that cannot write its receipt, state or anchor file for lack of space reports disk_full as its own code; the last good policy keeps enforcingFree space on the named filesystem and run the action again (deliver the bundle again)
machine_policy_failedLinux, macOSA vendor policy file could not be read or written. A connector you removed from guardrail.connectors whose file DefenseClaw cannot change (another tool holds it, for example with chattr +i) fails the run too: it rolls back (rolled_back) and the previous config stays in force. Invalid enterprise.machine_policy settings fail validation as config_invalid insteadCheck the file named in the message, make it writable, and run ensure again. See Machine policy
uninstall_failedLinux, macOSSome files, directories, or the service account could not be removedRead the message and run uninstall again
uninstall_incompleteLinux, macOSThe uninstall stopped before removing binaries that per-user hooks or vendor machine policy still name, and started the services again. On Linux, package removal also stops and keeps the package filesFix the cause the message names and run uninstall or package removal again
per_user_hooks_remainingLinux, macOSUninstall could not remove a user's DefenseClaw hook registrations for an agent; there is one error per user and agent, with the reason. Uninstall stops before it removes the binaries those registrations run. A manifest row that does not resolve to an account is refused before anything changes, and the error names the row. The home of a live account that is not available (it does not answer, its parent folder is missing, empty, such as the mount point of an unmounted volume, or cannot be read, or the home was moved or renamed aside, so its parent folder still holds another folder the account owns) is refused before anything changes too (uninstall_precheck_refused), so every service, the machine policy and the other users' hooks stay. A removed account or a re-homed account whose old home cannot be trusted is a warning instead (see Warnings)Remove DefenseClaw's entries from that agent's config in the current home, delete a stale copied receipt under that home's .defenseclaw/connector_backups/<agent>/ if it keeps naming another home, or correct or remove a named invalid receipt, then rerun uninstall. For a pending cleanup whose current home is missing or untrusted, fix the account's directory home to an existing directory it owns, without symlinks or group/other write, or remove the account. For a home that is not available, mount it or move it back to its home path, or recreate a deleted home folder as a folder the account owns, and rerun. Fix or remove an unresolved row in targets.yaml. ensure restores the deployment instead
replaced_hooks_not_fencedLinux, macOSBefore it stopped the gateway, the lifecycle could not fence a user's hooks of the release being replaced (the message names the user, the folder and why: a folder or _hardening.sh that is a symlink or not the user's, a home that did not answer). Until the guardian renders this release's hooks, such a hook follows its own fail mode while the gateway is stopped
replaced_hook_calls_runningLinux, macOSHook calls of the release being replaced (named by user and process ID) were still running 120 seconds after their hooks were fenced, and the lifecycle stopped the gateway. A call such a hook sends before the new gateway answers follows that release's fail mode. Usually the agent stalled its own hook
reconcile_failedLinux, macOSThe 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 warningRead each message. If it does not name a target, read the guardian log
downgrade_refusedallThe payload or package is older than the installed release. On Windows, ensure found a newer release installed than the Setup you ranTo go back on purpose, see Roll back (--allow-downgrade on Linux and macOS)
sandboxes_runningLinux, macOS packagesThe package install was refused before it changed anything: sandboxes run under the sandbox daemon of DefenseClaw 1.0.3 or older, which ends their MicroVM once the package replaces its program. The message names each sandbox and the command its user runs to end itHave each user end their sandboxes, then install the package again
product_floor_refusedLinux, macOS, Windows (Setup 1.0.6 and later)The confirmed signed bundle's min_product_version needs a later DefenseClaw release than this one, or the floor could not be read or checked. The rollback marker and --allow-downgrade do not lift it. An older Linux package's preinstall prints a refusal sentence without the code; macOS pkg preinstall records it in /opt/cisco/defenseclaw/lifecycle/last-package-result.json, and Windows Setup with JSON=1 reports it in errors[].codeCheck bundle status for current.min_product_version and install a release that meets the floor. To go below it, or when the bundle cannot be read, contact your administrator. Release floor limits gives the installer messages and result locations
config_rejectedLinux, macOSstatus 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 what failedFix what the lifecycle log names, then write config.yaml again, even unchanged, or push a corrected config or the previous one. See Change the config
powershell7_requiredWindowsPowerShell 7 (the x64 MSI) is not installed under Program FilesInstall PowerShell 7 x64
powershell7_untrustedWindowspwsh.exe is not a regular file, is writable by non-administrators, or is not signed by MicrosoftReinstall PowerShell 7 from the Microsoft MSI
powershell_execution_policyWindowsPowerShell refused to start the lifecycle script: a Group Policy execution policy (for example AllSigned) overrides -ExecutionPolicy Bypass, and the script signer is not in the Trusted Publishers store. Nothing was changedAdd the certificate that signs DefenseClaw to the computer's Trusted Publishers store, or set that policy to RemoteSigned or Unrestricted, then run it again. See Requirements
powershell_32bit_host, powershell_constrained_languageWindowsThe lifecycle was started in 32-bit PowerShell or in Constrained Language modeStart it from a 64-bit process in Full Language mode, or use the MDM wrapper
unsupported_architectureWindowsThe host is not native x64. x64 emulation on ARM64 is refusedUse an x64 device
ensure_refusedWindowsensure could not choose an action, for example because it could not read the installed deployment's metadataRead the message, then run repair
status_failedWindowsSetup /ensure could not read the deployment state. If the message says the managed path owner/group does not match the canonical descriptor, it names the affected install\deployment.json; when another account can change that file, the message names the account and the icacls command that removes its entry; /uninstall may also have warned untrusted_deployment_record for that pathRead the message. For that standalone record owner/group mismatch, inspect the owner as an administrator and restore its expected owner and group (BUILTIN\Administrators) if it belongs to this deployment. If /ensure still refuses, as a last resort run Setup /uninstall FORCE=1 PURGE=1 JSON=1 as LocalSystem, then run Setup /ensure CONFIG=<config.yaml> JSON=1 with an administrator-only config. For an ACL or reparse failure, follow the untrusted_deployment_record steps below before retrying /ensure
manifest_staging_failedWindowsensure could not prepare the first target manifest from the configCheck the config
lifecycle_launch_failedWindowsThe PowerShell 7 lifecycle did not start, or it printed no resultRead the message and enterprise-lifecycle.log
lifecycle_errorWindowsThe lifecycle reported a failure without a stable codeRead errors[].message and enterprise-lifecycle.log
rule_pack_unreadableWindowsThe gateway service account (NT SERVICE\DefenseClawGateway) cannot read the rule-pack folder the config names (guardrail.rule_pack or a guardrail.custom_packs path). Setup's config preflight reports it before changing anything (exit 1639). The message gives an icacls grant with the service's derived SID, which works before the service exists; a parent folder may need its printed RX grant tooRun the printed grant for the pack and any named parent folder, then run Setup again
not_readyWindowsThe run finished, but the deployment is not healthy. The message names the stopped services. verify also reports it when a required service has stoppedStart them with repair --profile standalone (or Setup /repair JSON=1) from an elevated prompt; otherwise run verify, then read the gateway and guardian logs
machine_policy_summary_missingWindowsC:\ProgramData\Cisco\DefenseClaw-HookRuntime is missing while accounts are enrolled, so their hooks cannot check for other machine hooksRun repair; the guardian writes the folder and summary back
gateway_start_failedWindowsstatus or verify found the gateway service not running; the message gives the last error the service logged and the log pathFix what the error names. If it says Access is denied, run repair from an elevated prompt
api_port_heldWindowsThe 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. status and verify report it even when that process answers the health check, and so does an install, upgrade or repair whose gateway never became ready. The message and api_port_holders[] name each process's PID, image and accountStop that process. The gateway keeps retrying and takes the port back by itself; after a failed install, run the install again. See Find what holds port 18970
scanner_runtime_unavailableWindowsverify found the skill, MCP and plugin scanner runtime (C:\ProgramData\Cisco\DefenseClaw-ScannerRuntime) missing, not prepared (also when a file of the unpacked runtime is missing or has another size, for example after antivirus quarantine), or changed outside DefenseClaw (state untrusted). The message names the file or the access problem. Every skill, MCP server and plugin install is blocked (fail-closed) until it is ready. status reports it as a warning; install, upgrade, repair and ensure fail with it (1603) when they could not install or prepare the runtimeRun Setup /repair or /ensure: they restore the runtime and its permissions from the Setup payload. enterprise windows repair from the installed CLI prepares or re-unpacks a damaged runtime but cannot reinstall a missing or changed one. When the message says timed out after 15m0s, the computer was short of CPU: run Setup /repair JSON=1 as LocalSystem again when it has CPU to spare; it continues the unpack. See Windows: Run Setup as LocalSystem
elevation_requiredWindowsA standard account ran enterprise windows status, verify, repair, upgrade, ensure, reconcile or uninstall, enterprise secret, or enterprise policy show. Only an elevated prompt can run the installer's own checks, read the protected state or change the deployment; nothing was changed. Exit 5. An unknown command exits 2, not 5Run the command from an elevated PowerShell prompt
preflight_failedWindowsA check before the lifecycle started failedRead the message
change_failedLinux, macOSenterprise secret set or another protected-state change could not be written before ensure applied itRead the message. Check that you ran it as root and that the secrets folder is writable by root
rotation_failedLinux, macOSrotate-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 failedFix 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[].

CodeOSMeaning
rolled_backLinux, macOSA failed action restored the previous deployment. The error beside it says why
bundle_state_unreadableLinux, macOS, WindowsPart of the policy bundle store could not be read or written (the current bundle, a receipt, or settling a killed run). When the current bundle cannot be read, ensure and repair on Linux and macOS keep the config the last deployment committed and still repair the host; the release floor is still checked, from the bundle's manifest. To replace it, contact your administrator. With --config, or with no committed config, the run stops with this code as an error and applies nothing
floor_checker_not_keptLinux, macOSA non-purge uninstall could not keep the copy of the gateway that package scripts use for the release floor check. The preinstall of a 1.0.4 or later package then cannot check the floor and installs its files; its postinstall ensure refuses a release below the floor, after the files are in place. A package older than 1.0.4 does not check the floor and completes below it. Install only releases that meet the floor on this device. See Release floor limits
product_below_floorLinux, macOS, Windows (1.0.6 and later)The installed release is below the confirmed bundle's min_product_version, for example after an older Setup or package that has no floor check. The policy keeps enforcing and nothing is repaired. Install a release that meets the floor; to stay below it, contact your administrator. See Release floor limits
recovered_interrupted_transactionLinux, macOSThis run found an interrupted run and rolled it back first
rotation_recoveredLinux, macOSThis run found an interrupted rotate-credentials and completed it (the new key had replaced the old one) or rolled it back
rotation_incompleteLinux, macOSstatus 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_installWindowsThis run rolled back a failed first install
rollback_leftoverWindowsThe rollback of a failed first install could not remove one item. The message names it and what removes it: run Setup /ensure and then /uninstall, both as LocalSystem while the accounts are signed in (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
user_runtime_folder_untrustedWindowsAn upgrade, ensure or uninstall could not verify or apply the permissions of an account's %USERPROFILE%\.defenseclaw folder or its hooks folder (for example a stale profile whose folder denies even Administrators). It changed nothing in that folder, left that account's old hook runtime copies there (they are inert), and went on with every other account. The message names each account and folder. Fix: Inspect the folder, reset its permissions or remove it if that account no longer uses DefenseClaw, then run the installed CLI's ensure again (& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows ensure --profile standalone from an elevated PowerShell prompt): it removes the old copies and lists them under changes
runtime_generations_not_collectedWindowsAn ensure that found the deployment compliant could not remove the old DefenseClaw hook runtime copies from the accounts' %USERPROFILE%\.defenseclaw\hooks folders, for example because another DefenseClaw lifecycle held the lifecycle lock. The copies are inert and the deployment is not affected; the message gives the reason. Fix: Run the installed CLI's ensure again (& 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows ensure --profile standalone from an elevated PowerShell prompt) once no other install, upgrade, repair or uninstall is running
claude_settings_hook_leftWindowsAfter the uninstall removed DefenseClaw's own Claude Code hook from a user's %USERPROFILE%\.claude\settings.json, the file still holds a hook command that names a DefenseClaw launcher (a hand-written or differently shaped one, which the uninstall keeps). Claude Code keeps running it and it fails. The message names each file and hook event. The uninstall itself succeeded. Fix: Remove those commands from the file as that user
security_incompleteLinux, macOS, Windowssecurity_complete is false. On Linux and macOS it is added whenever a check marked the field false (a result made false only by its errors gets none), and the message names the warning codes behind the field, for example security_complete is false because of: status_detail_unavailable, hook_process_fail_open; coverage_complete is true; each warning above says what to do. On Windows it names the actionable causes even next to hook_process_fail_open, and it is absent when only those agent limits explain the field. The message lists the reasons. "The claudecode machine policy is not verified in force" usually means the Claude Code attestation is missing or stale after an upgrade: confirm that an enrolled user's Claude Code runs DefenseClaw's hooks, then run the installed CLI's repair --attest-claude-effective-policy from an elevated PowerShell prompt (the Setup form is /repair ATTESTCLAUDEEFFECTIVEPOLICY=1; see Verify the install). "No account is enrolled for Codex, Claude Code or Cursor" means the target manifest has no enabled row for any of them: enable at least one under guardrail.connectors, check the enrollment lists (see Enrollment), and apply the config with Setup /ensure CONFIG=<path>
config_version_8Linux, macOSThe config the run read (--config, or the installed config.yaml) is still config_version: 8. DefenseClaw applied its version 9 migration; the message lists the values that conflicted and how the migration resolved them. Deliver a config_version: 9 file instead, for example the migrated config.yaml
machine_policy_incompleteLinux, macOS, WindowsDefenseClaw's hooks are not in place in a vendor policy file for the named connectors, or they are in place but do not take effect (a higher-precedence source such as a com.anthropic.claudecode managed-preferences profile outranks them, or the file carries a conflicting value such as allow_managed_hooks_only = false). security_complete is false, and verify fails with verify_failed. When entries the last transaction placed are gone from their file, status fails too and repair puts them back; under ownership: verify_only the message names the export to deploy instead. On Windows, status and verify fail with it while DefenseClaw's Claude Code drop-in (managed-settings.d\90-defenseclaw.json) was changed or removed outside DefenseClaw; the hook guardian puts it back at its next pass, and an elevated repair (or reconcile) puts it back when the guardian is stopped
hook_process_fail_openLinux, macOS, WindowsAn enabled agent runs a tool when its pre-tool hook is stopped, killed or times out (Codex, Claude Code, Copilot CLI, Antigravity and others; the message names the agent). security_complete is false while it is enabled. It is an agent limit, not DefenseClaw's hook fail mode (which covers a gateway that does not answer; with fail mode closed, the managed default, the hook still fails closed then). The message names the connector's fail mode when the config can be read. Protect the hook process with application control or EDR. See Known limits
codex_requirements_heldWindowsAnother process holds C:\ProgramData\OpenAI\Codex\requirements.toml open, so a Codex policy update waits. The message names the process where Windows can tell. The enforced policy already in place stays in effect. If the holder lets go within 30 seconds of the failed attempt, the running command applies the update. Otherwise the guardian applies it at its next pass, about a minute later, and a failed Setup run needs the administrator to run it again. This is a Windows platform limit: Codex reads the file as each user, so any user can hold it open (Windows)
codex_state_unsettledWindowsSetup could not judge the Codex managed-hooks state because the Codex writer's transaction counter stayed odd for 30 seconds: a writer stopped in the middle of a transaction. The run stopped: an install, repair, ensure or upgrade that had started is rolled back (an upgrade returns to the release it came from), and a verify changes nothing. Run the Setup /repair command the message names; the next Codex writer pass ends the stopped transaction. When the rollback met the same writer it ends with the transaction still pending, the restored services running and exit 1618; /repair finishes it once the writer is gone.
managed_launch_uninspectedLinux, macOSA running enrolled agent can start without its managed hook. For Devin, Copilot CLI and Codex, an inherited BASH_ENV or SHELLOPTS with noexec can prevent Bash from reaching the registered hook command. The warning names the account and PID, and coverage_complete is false; verify fails. End that agent process, clear the setting in its launch environment, and start it again. See Hooks the agent cannot start for the detection limit.
status_detail_unavailableLinux, macOS, WindowsStatus could not read one of its inputs for a connector block, so that block leaves out what the input feeds; on Windows it comes with Hermes NOT COVERED when a session-only HERMES_HOME cannot be observed
claude_state_unreadableLinux, macOS, WindowsThe guardian could not read an enrolled user's ~/.claude.json, so the gateway refuses that user's Claude Code MCP servers until it can. The message names the account
scanner_judge_missingWindowsWith scanners.skill_scanner.use_llm: false, Scanners: shows judge none; scans use static analyzers without an LLM judge. The warning also appears when no judge model is configured. Set scanners.skill_scanner.use_llm: true, configure llm.model and store its key with enterprise secret set to enable the judge
claude_version_floor_missingLinux, macOSDefenseClaw'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_startedLinux, macOS, WindowsInstalled with --no-start (Setup NOSTART=1 on Windows). ensure reports it as a warning (on Windows also install, upgrade and repair, which exit 0); status and verify fail until the services run, because no agent is protected. Run repair or ensure (on Windows without NOSTART=1) to start them
adopted_existing_layoutLinux, macOS--adopt-existing backed up the old layout to the lifecycle directory
selinux_relabelLinuxrestorecon failed after the files were written
selinux_moduleLinuxThe lifecycle could not load (or, on uninstall, remove) the DefenseClaw SELinux module; the message has semodule's error. Only SELinux-confined users depend on it
selinux_module_missingLinuxstatus or verify found SELinux enabled without the DefenseClaw SELinux module, the hook socket without its defenseclaw_hook_sock_t label, or the gateway binary without its defenseclaw_gateway_exec_t label. SELinux-confined users (user_u, staff_u and other confined logins) then cannot reach the hook socket, and their hooks are refused with enterprise_managed_hook_socket_selinux_denied. Run repair
judge_failingLinux, macOS, WindowsThe gateway's /health reports the LLM judge as failing (every recent call failed) or unavailable. Prompts still get the rule-pack verdicts, but not the judge's checks, until it recovers. The message has the last error; check the judge's provider credentials and network
llm_model_unroutableLinux, macOS, Windowsensure (and on Windows also status and verify) found an llm.model the gateway cannot route: a Bedrock model (llm.provider: bedrock or a bedrock/ prefix) that is not a Bedrock model id, ARN or deployment alias, or a value with no provider that is no known model name, such as a short name (luna, haiku-4.5). The config is applied, but the LLM judge falls back to the rules on every call. Write provider/model or the full Bedrock id (for example us.openai.gpt-5.6-luna), then run ensure again
disk_space_lowLinux, macOSstatus or verify found less than 256 MiB, or less than 2%, free on the filesystem that holds the gateway's audit database or logs; below 16 MiB the message says the filesystem is full. When the audit database cannot be written, managed hooks block agent prompts and tool calls (fail closed, see Fail modes): the block message says that DefenseClaw could not write the call's audit record. Free space on the filesystem the message names; agent work resumes by itself, without a restart. A gateway that stops while the disk is full starts again once there is space
audit_write_failedLinux, macOSThe gateway's /health reports that it cannot write the mandatory audit records, or that a write failed since it started. While the records fail, managed hooks block the calls whose records fail (fail closed). A full class means the audit filesystem is full: free space on it (see disk_space_low). The warning clears 16 minutes after the last failed write
unit_drop_inLinuxA local systemd drop-in that DefenseClaw did not write changes a DefenseClaw unit (environment, limits, timeouts) but keeps its account, sandbox and config. The message names the files. A drop-in that changes those fails status and verify instead
ai_defense_unavailableLinux, macOSCisco 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
directory_lookups_failingLinux, macOSThe gateway cannot resolve some accounts in the directory (a domain controller or SSSD that does not answer, or an account in more than 2,048 groups). Requests whose assignments need facts absent from the cache are refused with the missing fact named (default_lookup_failed), and cached facts are dropped after an hour. Status stays ok. The message names the failing accounts by uid. Run /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux profile-explain --user <account> (/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos profile-explain --user <account> on macOS) for the reason, and check sssctl domain-status and getent passwd <account> on Linux, or dsconfigad -show on macOS. On a bound Mac an Active Directory account counts as failing while odutil show nodenames lists the domain node Offline; sudo dscacheutil -flushcache; sudo dsmemberutil flushcache makes the Mac list the domain groups again at once. The warning clears when the lookups work again, or 15 minutes after the last failed one
per_user_hooks_remainingLinux, macOSThe account was removed, or the home folder of a live account was deleted, so uninstall could not remove that user's hook registrations for the named agent and went on without them. A home moved or renamed aside (its parent folder still holds another folder the account owns) is not deleted: uninstall refuses instead (see Lifecycle error codes). A warning about an account with no directory home names its recorded home and what may remain. After a live account is re-homed, the guardian cleans its current home and its old home when it still exists and is trusted; the row stays while a report is missing, a path lies outside the home it cleaned, or the current home still has DefenseClaw entries, and the warning names the path or receipt. An untrusted old home also keeps the row. Remove DefenseClaw's entries from the named agent's config in the current home, delete a stale copied receipt under its .defenseclaw/connector_backups/<agent>/ if it keeps naming the other home, or correct or remove a named invalid receipt, and rerun. For an untrusted old home, remove its entries, delete that home if unused, or fix its owner or permissions so the guardian can clean it. Other removal failures stop uninstall; see Lifecycle error codes
per_user_state_remainingLinux, macOS, Windowsuninstall --purge (Setup PURGE=1 on Windows) could not remove a user's DefenseClaw folder; 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. Run Setup /ensure and then /uninstall PURGE=1, both as LocalSystem while the accounts are signed in (see Run Setup as LocalSystem)
root_squattedWindowsA standard user created C:\ProgramData\Cisco, C:\ProgramData\Cisco\DefenseClaw or C:\ProgramData\Cisco\DefenseClaw-Lifecycle before DefenseClaw (the default ProgramData permissions allow it). Install and Setup /ensure remove a junction or symbolic link there as a link and move a folder or file aside to <name>.untrusted-<UTC time>-<id>; the warning names the path, what it was, the account that created it and the new name. Other actions refuse with root_squatted until an install has run. Review the .untrusted- copy, then delete it from an elevated prompt: Remove-Item -LiteralPath "<path>" -Recurse -Force
untrusted_deployment_recordWindowsProfile resolution ignored the named record because its trust check failed. For a Secure Client record, the warning keeps its original text: have the Secure Client administrator inspect that deployment's record and use its recovery procedure; Standalone Setup cannot repair it. For a standalone record with an untrusted owner, inspect the owner as an administrator and restore the expected owner and group (BUILTIN\Administrators) if the record belongs to this deployment. If /ensure still refuses, as a last resort run Standalone Setup /uninstall FORCE=1 PURGE=1 JSON=1 as LocalSystem, then run /ensure CONFIG=<config.yaml> JSON=1 with an administrator-only config. For unsafe permissions or a reparse point, inspect the named trust failure; after confirming its origin, remove the untrusted standalone deployment record, replace any reparse point with a regular path, and correct unsafe permissions on the named path and affected ancestors. A forced metadata-free purge can keep StateRoot and the bad record, so remove or fix those paths before a fresh Standalone Setup /ensure CONFIG=<config.yaml> JSON=1
machine_state_remainingWindowsSetup /uninstall or the MDM uninstall script could not remove a machine folder DefenseClaw created outside its state folder: a DefenseClaw-PowerShell-<32 hex>, DefenseClaw-Installer-<32 hex> or DefenseClaw-Bootstrap-<32 hex> folder an interrupted elevated command left. The message gives each path and the reason. Remove them from an elevated prompt
machine_state_keptWindowsSetup /uninstall PURGE=1 kept a machine file on purpose, for example a runtime selector state in an agent's policy folder that also holds the selections of another DefenseClaw deployment. The message gives each path and why it stays. Leave it in place; that deployment's own uninstall removes it.
created_folders_keptWindowsA purge left a vendor folder in place, such as C:\ProgramData\Cursor or C:\Program Files\ClaudeCode. The message gives the path and the reason: it holds another program's files, someone other than an administrator can change it, or a link is on its path. A folder DefenseClaw created keeps its record in C:\ProgramData\Cisco\DefenseClaw-Lifecycle\created-folders, so the next purge tries again once the cause is gone. Check the folder; remove it by hand only if nothing else uses it.
mdm_rotation_journal_keptWindowsAn uninstall removed the deployment but not the MDM kit's credential rotation journal C:\ProgramData\Cisco\DefenseClaw-MDM\rotation, which can hold a copy of an earlier credential. A plain uninstall keeps it on purpose: run the uninstall again with PURGE=1 to remove it. A purge leaves it only when the folder is not administrator-only or holds something the kit does not write (a folder or a link); the message names what it found. Check that folder and remove it by hand.
native_otlp_product_credentialLinux, macOSverify found an account's own Codex or Claude Code configuration with a native OTLP exporter that sends the DefenseClaw gateway token to a port the managed gateway does not serve. Prompt telemetry would go to whatever holds that port, so security_complete is false. The guardian removes the exporter on its next pass. If the file cannot be edited (immutable or unwritable), remove the exporter by hand. An operator collector with its own bearer is kept as it is
native_otlp_config_uncheckedLinux, macOS, Windowsverify could not read an account's Codex or Claude Code configuration to check it for that exporter. The message names the account, the file and the reason. Fix the cause and run verify again. On Windows status and verify show it when the configuration the agent reads reaches a file the account does not own, through a link or outside the profile, so DefenseClaw cannot check it and repair leaves it as it is: replace it with the account's own file, or remove the link, and the next repair checks it
agent_settings_not_restored (exporter removed)WindowsThe managed install took back the native OTLP exporter of an earlier per-user DefenseClaw install: the OTEL_* env entries in the account's .claude\settings.json (Claude Code) or the [otel] exporter tables in its .codex\config.toml (Codex). It carried both DefenseClaw headers and sent to a loopback port the managed gateway does not serve. The message says "the managed install removed the ... of an earlier per-user DefenseClaw install". A copy of the file as it was is kept beside it, .claude\settings.json.defenseclaw-otlp-removed.bak or .codex\config.toml.defenseclaw-otlp-removed.bak, and status and verify show this warning while the copy is there. If that exporter was the account's own collector, put it back from the copy. Delete the copy to clear the warning. An exporter of any other shape stays in place, and the hook guardian's log names the file, the fields and the step to take by hand
agent_settings_not_restored (exporter not removed)WindowsThe managed install could not remove an earlier per-user install's native OTLP exporter from the account's Codex or Claude Code configuration (for example a configuration on a network share). The message says the file "still holds the native OTLP exporter of an earlier per-user DefenseClaw install". Its DefenseClaw credential is revoked. The guardian retries at sign-in and then at most every 15 minutes. If the file is a link it never rewrites, remove the exporter by hand as that user, then run repair (or the next ensure), which checks again and clears the warning
user_cleanup_failingWindowsstatus or verify found that the hook guardian failed, on three or more passes, to remove DefenseClaw's registration of a connector an account is no longer enrolled for (for example after you disabled OpenCode). The message names the connector, the account folder and the last reason; the guardian keeps retrying. Fix what the reason names, then run repair
user_registrations_pending, user_registrations_failedWindowsUninstall could not act as some users (no active, connected session, or the uninstall did not run as LocalSystem), or a per-user removal failed. The warning lists each account with its connectors. What stays is inert. Run Setup /ensure and then /uninstall, both as LocalSystem while the accounts have an active session (reconnect a disconnected one first)
package_install_failedLinux, macOSThe package's own install run (last-package-result.json in the lifecycle directory) failed: with no deployment, nothing is active; with a deployment, the last package install, reinstall or upgrade did not apply and the deployment keeps running as it was. 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_requiredWindowsA standard account ran a command that needs elevation. Exit 5; nothing was changed. See Lifecycle error codes
health_not_checkedWindowsThe 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.gateway, readiness.guardian, coverage_complete and security_complete read false because they were not checked. installed_version is the recorded version when an administrator gave an unknown --profile; it is omitted for a standard account, which cannot read the deployment record. For the deployment's health, run enterprise windows verify --json from an elevated PowerShell prompt
deleted_account_rowsWindowsA local account was deleted. The enumerator drops its enrollment rows at its next pass, also when its profile folder is still there. Until then the guardian's failures for that account are reported here, status and verify stay healthy, and Setup /ensure is not blocked. Domain and Microsoft Entra accounts are not checked, because their lookup also fails while the directory cannot be reached
enrollment_pending_account_folderWindowsAn 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, and a fresh Setup install takes it over at once; repair leaves it alone until then
hook_contract_unverifiedallA user runs an agent version that has no verified DefenseClaw hook contract, so that agent runs without DefenseClaw hooks. coverage_complete and security_complete are false; verify warns for that account and does not fail
opencode_port_account_unknownLinux, macOS, WindowsThe guardian could not read or write an account's OpenCode service.json (a linked or read-only ~/.config/opencode, a broken file, a home that does not answer). Its recorded port does not change and other accounts are not affected. The line names the account, the file, the reason and the step that clears it. For an entry whose UID has no account any more it reads OpenCode port record for UID <n> (no account found) and names opencode-port-unknown-clear <uid> --yes, which refuses while the UID still resolves (OpenCode).
opencode_port_contestedLinux, macOS, WindowsA port stays held when several files named it in the import pass, or an imported file could not be rewritten. Repair the affected account file and run the clear command named in the warning; the command changes only that port mark.
opencode_port_record_unreadableLinux, macOS, WindowsThe guardian's OpenCode port record cannot be read: no account gets a new port until it can. Repair it, or remove it to rebuild it from the accounts' files on the next pass.
opencode_port_record_uncheckedLinux, macOS, WindowsA non-root or non-elevated status cannot open the guardian's folder; run status as root or in an elevated console.
opencode_v1_unprotectedallA user can run OpenCode V1 (opencode-ai 1.x). V1 loads the OpenCode V2 plugin DefenseClaw installs but never runs it, so OpenCode is not protected for that user. The message names the copy; a machine-wide copy several users share is one line with the number of users and names none of them (the root-only unprotected-agents.json beside the target manifest names them), a copy in one user's home gets its own line. A user whose own run of that copy's launcher (<prefix>/bin/opencode) printed no version is counted in the same line, not given a hook_contract_unverified line of their own. coverage_complete and security_complete are false; verify warns and does not fail, and nothing is blocked or removed. Remove V1 (npm uninstall -g opencode-ai, with the --prefix it was installed under), install V2 (npm install -g @opencode/cli@2), and run opencode service restart as the user. The warning clears at the next enumerator scan (within five minutes)
agent_install_scan_incompleteLinux, macOS, WindowsThe bounded scan of an enrolled user's agent installs could not finish; the warning names the part (a version manager over its 64-version bound, a home too large or partly unlistable, an editor extensions folder over its bound, too many copies, an account the cycle could not inspect or could not confirm gone). coverage_complete and security_complete are false. On Windows a home walk that outlasts its share of a cycle (for example on a host still busy right after an upgrade) keeps running for up to 2 minutes, and the enumerator publishes again as soon as it finishes, so the warning clears within a few minutes; if it stays, the home is too large or partly unlistable. Review the account's home and use application control to block unapproved agent binaries; see Vendor limits
agent_unprotectedallThe enumerator found an agent installed for a user but could not enroll it, or could not finish the Windows per-user WinGet package listing; the message gives the reason. security_complete is false; verify warns for that account and does not fail. On Windows this also covers a running enabled agent whose account SID cannot be resolved, and an account whose WinGet listing reaches the entry limit or deadline ("not fully scanned"). See Enrollment
agent_settings_not_restoredLinux, macOS, WindowsOn Windows this code also reports an earlier per-user install's native OTLP exporter (the two Windows rows above). The hook guardian put back a missing Hermes config.yaml or Devin config.json from the last known good copy or the pristine backup, or recreated it with DefenseClaw's hooks only when no copy was available. Review the account's settings: changes after the copy may be missing. The warning clears at the next successful guardian refresh. A restore that could not bring the settings back stays reported (settings_lost) until they return. This warning alone does not fail verify, set security_complete to false or fail MDM detection
guardian_target_failedLinux, macOSThe 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_pathLinux, macOSThe 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 the reverse), or a folder the user made unreadable. An unreadable ~/.defenseclaw or ~/.defenseclaw/hooks is not on this list: the guardian sets it back to 0700. 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. 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_removedLinux, macOSA target's account no longer exists (the directory answers "no such account"), usually because it was deleted. The enumerator removes the target after three consecutive definitive misses, one per cycle, and enterprise linux repair or enterprise macos repair removes it at once. A warning only: verify, reconcile, detect.sh --require-healthy and security_complete do not fail on it. A directory outage that hides an account does not produce it: directory_lookups_failing reports the outage, and the target stays
guardian_cleanup_pendingLinux, macOSA 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. A warning only. See Enrollment
guardian_repair_pendingLinux, macOSA DefenseClaw hook file of an enrolled account (a hook script, the connector's hook token or its runtime record) no longer holds what the hook guardian left there at its last pass, so that agent's hook calls may not be inspected until the guardian puts it back. The guardian reacts within a few seconds and the warning clears after that pass; security_complete is false meanwhile. The same code reports a guardian record that cannot be read. Run status again after a minute. If the warning stays, check the guardian log and the account's ~/.defenseclaw/hooks folder
guardian_repair_pendingWindowsThe hook guardian's last pass could not verify an enrolled account's agent (for example a deleted hook file of an account that is signed out or disconnected, which the guardian repairs only in that account's own session), or a hook file it verified is missing now. security_complete is false and the warning names the account and the agent. Sign the account in (or reconnect its session), then run enterprise windows status again
enrolled_home_unavailableLinux, macOSAn account that targets.yaml still enrolls has a home that cannot currently be found. This can be a temporary mount outage; a missing home alone does not prove deletion. Enrollment is kept and retried on the next hook enumerator pass. This is a warning only: verify and security_complete do not fail on it.
guardian_user_file_pendingLinux, macOSThe guardian has not yet had its first pass for a newly enrolled user, so that user's DefenseClaw-owned per-user hook file (Copilot's VS Code Local hook file) is not written yet. It writes it within a minute or two. A warning only. Once written, a missing or edited copy fails status and verify until the guardian rewrites it
per_user_gateway_runningLinux, macOSAn 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
agent_sessions_restart_requiredLinux, macOS, WindowsA user runs an agent CLI (Claude Code, Codex and the other connectors) that started before the deployment was activated, for example one left open through an uninstall and a reinstall. An agent reads its hooks when it starts, so that session runs without DefenseClaw. A Codex session is named as well: it keeps the requirements it read when it started. A Codex background server (app-server daemon) that started before the activation is named with its own fix: new Codex sessions refuse it until the user runs codex app-server daemon restart (or starts codex --no-daemon). A Claude Code session open while the DefenseClaw drop-in was changed or removed is named as well. The warning also names a Hermes or other per-user agent session started before the guardian put back hooks the user changed or removed, or before the guardian first wrote a newly enrolled user's hooks (within about five minutes of enrollment); security_complete stays false until it restarts. On Windows the restore case excludes Claude Code, Codex and Cursor, whose hooks are machine policy; on Linux and macOS it excludes the machine-policy connectors (Codex among them). A guardian restore record that cannot be read reports "restart status unknown" and sets security_complete to false, even when no session was listed. A process with no account name is checked by its owner SID. Ask the user named in the message to restart those agent sessions; if the owner is unknown, identify the account, and if the restore record is unreadable, resolve that read failure and recheck
no_connectors_enabledLinux, macOS, WindowsThe config enables no agent under guardrail.connectors (on Linux and macOS: while the enumerator found eligible users), so nobody is protected. security_complete is false, and verify fails (on Windows its error carries this code). An empty entry such as claudecode: {} enables that agent, and per-user agents count too. Add the agents to protect under guardrail.connectors and apply the config; see Choose the agents to protect
unmanaged_leftoversLinux, macOSstatus or verify found DefenseClaw state with no deployment. Use uninstall --purge to remove it
unit_failedLinux, macOSA 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_changedLinux, macOSconfig.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. When the failed run is the Linux apply trigger itself, it starts the trigger again after 30, 60 and then 120 s; after three retries for the same config.yaml the warning says retry limit reached and you run ensure yourself
policy_not_appliedLinux, macOS, WindowsAfter install, upgrade, repair or ensure, the gateway is ready but reports another effective policy digest than the installed config computes to. The message gives both and says the gateway applies the config on its next reload. On Linux and macOS status warns policy_not_applied with policy.applied: false and security_complete: false, and verify reports it as an error and exits 1. On Windows status warns policy_not_applied with the installed CLI's repair as the next step (enterprise windows repair --profile standalone, by its full path from an elevated PowerShell prompt; see Repair), security_complete is false, and verify fails (exit 1603). See Effective policy digest
policy_reload_rejectedLinux, macOS, WindowsEvery action, status and verify included: the gateway rejected its last policy reload (an edited rule pack, scanners.mcp_scanner.yara.extra_rules file or custom skill scanner policy that no longer matches its pinned digest, a Rego module that does not parse) and keeps enforcing the previous policy. The message gives the reason, and policy.last_reload_error carries the same text. The gateway clears it when a later reload succeeds; nothing needs restarting
local_enforcement_entries_ignoredLinux, macOS, WindowsThe run migrated a config_version: 8 config on a host whose audit.db holds N local block or allow entries. The message reads "N local block/allow entries in audit.db are ignored; the administrator config is the policy". They are neither imported nor deleted. Add the ones you want to asset_policy in the admin config. See Policy changes on a managed host
scanner_runtime_unavailableWindowsstatus found the scanner runtime missing, not prepared or changed outside DefenseClaw, or install, upgrade, repair or ensure could not install or prepare it; the message gives the reason and the command that restores it. Every skill, MCP server and plugin install is blocked until it is ready, and verify fails with the same code. See Lifecycle error codes
config_revertedLinux, macOSAn 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
config_revertedWindowsconfig.yaml had been changed outside the lifecycle (its hash is not the one config.generation.json records); ensure put the managed config back and kept the edited file as rejected-config.yaml next to it, readable by administrators only. A config.yaml that does not parse is kept the same way by Setup /ensure CONFIG= and /repair CONFIG=; a run without CONFIG= refuses before any change and says to supply one
lifecycle_supersededLinux, macOSA queued apply run of an older binary found a newer release installed while it waited, and stood down; the installed binary applies later changes
upgrade_rolled_backLinux, macOSIn the apply trigger result (lifecycle.log on macOS, the journal of defenseclaw-enterprise-apply.service on Linux): a package upgrade failed and was rolled back, its newer binaries stay installed, and config.yaml and the protected credentials are still the ones the restored deployment applied, so the apply trigger did not retry the upgrade. The package result says why it failed. Fix that, then install the package again, or run enterprise linux ensure --from-package (enterprise macos ensure --from-package)
guardian_report_pendingLinux, macOSAfter a change the guardian had not reported its targets within 30 seconds. Run status or verify a moment later
guardian_reconcile_pendingLinux, macOStargets.yaml changed in the last three minutes (an apply, ensure or an enumerator cycle) and the guardian has not reconciled it yet. It does within about a minute, and until then enforces the targets it last reconciled. No repair is needed; run verify again a minute later. A guardian that stays behind an older targets.yaml fails verify
package_installed, package_upgradedLinux, macOSIn 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_repairWindowsThe action that ensure chose, and why. ensure_upgrade means a newer release was installed
ensure_config_restartWindowsensure applied a config change to the installed release through the lifecycle transaction and upgraded nothing: a changed key is one the services read only at start (such as enterprise.machine_policy), or the running gateway could not take the change. Every service stopped and started again, which takes two to six minutes; the message names the keys. A change of only the managed_hooks_only setting restarts only the hook guardian and the gateway (about a minute), and the message says so. See Restart or repair the gateway
codex_machine_folder_linkWindowsA link or a file sits on the path of the Codex machine-policy folder (C:\ProgramData\OpenAI\Codex). The hook guardian does not follow, change or remove it, so it cannot recreate or repair the folder and Codex is not protected. The message gives the command that removes the link: cmd /c rmdir "<link>". See the guardian log repeats a Codex folder failure
cursor_machine_folder_linkWindowsA link or a file sits on the path of the Cursor machine-policy folder (C:\ProgramData\Cursor). The hook guardian does not follow, change or remove it, so it cannot recreate or repair the folder and Cursor is not protected. The message gives the command that removes the link: cmd /c rmdir "<link>". See the guardian log repeats a Codex folder failure
claudecode_machine_folder_linkWindowsA link or a file sits on the path of the Claude Code machine-policy folder (C:\Program Files\ClaudeCode). The hook guardian does not follow, change or remove it, so it cannot recreate or repair the folder and Claude Code is not protected. The message gives the command that removes the link: cmd /c rmdir "<link>". See the guardian log repeats a Codex folder failure
guardian_repaired_driftWindowsSince the last lifecycle run, the hook guardian put back the protection of a managed object that had drifted, such as write access another account was given on the runtime folder. The message names the object, the time and the drift. Nothing is left to fix; find out who changed the permission
runtime_acl_not_repairedWindowsensure found the access control of the runtime folder drifted (an extra entry that grants no write, or a missing service entry) and could not put it back. The message names the folder, the drift and the cause. Run ensure again; if the warning stays, run repair
ensure_config_failedWindowsensure ran the lifecycle transaction for a config change on the installed release and upgraded nothing, but the transaction failed or rolled back, so the change is not confirmed applied. The errors in the same result say what failed; fix that and run Setup /ensure again
ensure_config_appliedWindowsensure applied a config-only change in the running gateway and stopped no service; the message lists the changed keys. See Restart or repair the gateway
custom_pack_will_not_loadWindowsA guardrail.custom_packs entry that no setting selects would not load if one did: its folder is missing, the pack is invalid, or its digest pin does not match the files (the message gives the files digest). The config was applied; a config that selects the pack is refused until the pin matches. Review the pack, then put the files digest in guardrail.custom_packs.NAME.digest and run Setup /ensure again, or remove the entry
policy_reload_rejectedWindowsThe gateway rejected the last policy change (for example a rule pack edited away from the digest guardrail.custom_packs pins) and keeps enforcing an earlier policy. The message gives its error; policy.last_reload_error and policy.applied: false say the same. verify fails with this code (exit 1603). Restore the asset or apply a corrected config
policy_not_buildableWindowsThe installed config and the assets it names no longer build into a policy (a pinned rule pack that no longer matches, for example); the gateway keeps enforcing the earlier policy, and the message names the error
config_edited_outside_lifecycleWindowsconfig.yaml was changed by hand: config.generation.json does not record its hash, and the gateway may already enforce it. The hook guardian records such a write as the next config generation (actor hand-edit:unattributed) within about a minute, but never while a Setup run or an interrupted install transaction owns config.yaml: Setup records what it writes there itself, as lifecycle; the warning stays and then says the generation "records it as a hand edit". The guardian keeps the hash of the last hand edit in config.hand-edit.json, also when it cannot record the edit yet (a Setup run holds the lifecycle lock, or the lock or the lifecycle folder cannot be read; it logs why once and retries each cycle). A Setup run or rollback that finds those bytes unrecorded and did not install them from CONFIG= records them as the hand edit, never as lifecycle; ensure CONFIG= with exactly those bytes approves them. Run ensure with the intended config to put the managed config back. On a computer that takes signed policy bundles the same result also carries the error bundle_not_applied (exit 1603) while config.yaml is not the confirmed bundle's config; ensure without CONFIG= re-applies the bundle
bundle_config_restoredWindowsensure or repair put the confirmed bundle's config back over a config.yaml changed outside the lifecycle and kept the edited file as rejected-config.yaml, or wrote it in place of a deleted config.yaml
bundle_restore_deferredWindowsconfig.yaml is not the confirmed bundle's config, but an install transaction is pending: the run recovers it first (which puts back the config the transaction recorded) and does not re-apply the bundle, so the run fails with bundle_not_applied while config.yaml is still not the bundle's config. Run ensure again; the Intune remediation does on its next run
policy_state_unrecordedWindowspolicy-state.json could not be written next to deployment.json. The result itself stands
registration_failed, lifecycle_log_failedWindowsThe registry marker, the Add/Remove Programs entry, or the lifecycle log could not be written. The result itself stands

Kernel sensor warnings

These appear in status and verify on Linux when the sensor helper uses Tetragon (see Tetragon on a Linux fleet). They are warnings: a problem with your Tetragon never fails enterprise linux verify, and security_complete does not depend on it. enterprise linux tetragon verify, the readiness check for a mode, does fail while Tetragon is down or refused. The managed defenseclaw command runs only the commands in Managed command availability, so run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux tetragon verify first: it prints the failing check with the command that fixes it. On a per-user install, defenseclaw doctor has a Kernel sensor (Tetragon) row with two codes: tetragon-tcp-api (in brackets below) and tetragon-not-used-per-user. Every message reads <what happened> (<impact>); <next step>.

CodeMeaningFix
tetragon_unavailableThe sensor helper cannot reach Tetragon (stopped, no socket, or a failing stream). Plane C uses cn_proc and fanotify, and no kernel control is enforcedCheck it with systemctl status tetragon and start it with sudo systemctl start tetragon. Nothing is wrong with DefenseClaw; kernel enforcement is off until Tetragon returns
tetragon_tcp_api [tetragon-tcp-api]Tetragon serves its API on a TCP address, which any local account can use to load kernel policies. The helper never dials it, so observe and enforce are refusedecho unix:///var/run/tetragon/tetragon.sock | sudo tee /etc/tetragon/tetragon.conf.d/server-address, then sudo systemctl restart tetragon (this drops policies added with tetra; tetragon.tp.d policies reload)
tetragon_untrusted_endpointThe info file /var/run/tetragon/tetragon-info.json or its folder is not owned by root or is writable by its group or others, the socket or its folder is not owned by root or is writable by others, or the socket is not served by root and the pid in the info file. The helper does not connectRestore the owner and mode the message names, or sudo systemctl restart tetragon (this drops policies added with tetra; tetragon.tp.d policies reload) so Tetragon recreates the socket
tetragon_unsupported_versionThe Tetragon version is not supported for this mode: consume works on 1.6 and 1.7, observe and enforce need 1.7. Plane C uses cn_proc and fanotifyInstall Tetragon 1.7.x, or keep mode: consume on 1.6
tetragon_persistent_sensorsTetragon runs with keep-sensors-on-exit on, or its config cannot be read, so stopping it would leave programs enforcing with nobody updating them. enforce stays in monitor modeecho false | sudo tee /etc/tetragon/tetragon.conf.d/keep-sensors-on-exit, sudo systemctl restart tetragon (this drops policies added with tetra; tetragon.tp.d policies reload), then remove leftover pins under /sys/fs/bpf/tetragon
tetragon_plane_c_offenterprise.tetragon.mode is set, but AI Discovery Plane C is off, so the helper runs with Tetragon offSet ai_discovery.runtime.enabled: true and ai_discovery.runtime.enable_host_plane: true in the admin config and apply it
tetragon_config_invalid:<variable>The helper's drop-in 30-defenseclaw-tetragon.conf has a malformed value for the variable, so the helper used the safe default (consume, 168h, no approval, or no such connector)sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair writes the drop-in again from config.yaml
tetragon_identity_unknownTetragon's pid is not known from /var/run/tetragon/tetragon-info.json, so nothing is loadedsudo systemctl restart tetragon (this drops policies added with tetra; tetragon.tp.d policies reload), so Tetragon rewrites the file
tetragon_not_applicablemacOS: the config carries enterprise.tetragon, which only Linux usesRemove enterprise.tetragon from this OS's config to silence it
tetragon_foreign_defenseclaw_name:<name>A policy in Tetragon has a name of DefenseClaw's own form (defenseclaw-observe-, -connect-, -controls- or -controls-burnin- and eight hex digits) that this helper did not record loading. DefenseClaw treats it as yours, lists it under your policies and never changes itRename your policy so it does not read like one of DefenseClaw's
tetragon_customer_events_cappedN events of your policy <name> were not forwarded in the last hour: they went over the per-policy limit of 20 a second, which applies before DefenseClaw looks for an AI agent. The counts stay exactNothing to do, or set enterprise.tetragon.customer_events: off in the admin config
kernel_lsm_unavailableBPF LSM is off on this kernel, so the controls cannot deny and stay in monitor modeAdd bpf to the kernel's lsm= boot parameter and reboot (cat /sys/kernel/security/lsm shows it). See Tetragon on a Linux fleet
kernel_enforce_ack_missingmode: enforce has no enforce_ack, so the controls stay in monitor modeReview sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux tetragon verify --ready-for enforce, then set enterprise.tetragon.enforce_ack to the digest it prints in the admin config and apply it
kernel_enforce_ack_staleenforce_ack does not include this build's digest (a release changed a control), so every user is in monitor modeReview the release notes and verify --ready-for enforce, then set enforce_ack to the new digest, or to a list of the old and the new digest while the rings upgrade
kernel_enforce_guardrail_observe:<connector>The connector is in observe mode, so its agents are monitored and never deniedTo deny for it, set guardrail.connectors.<connector>.mode: action in the admin config, or leave it monitor-only
kernel_enforce_pausedKernel enforcement on this computer is paused until the time the warning gives (it also names who set it and why), so every user is in monitor modesudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux tetragon resume, or wait for the expiry
kernel_pause_file_invalidA pause file is present but is not a root-owned regular file or cannot be read, so enforcement stays pausedRemove it with sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux tetragon resume
kernel_enforce_inactiveNothing can be enforced. Either no enrolled user has an anchored command-line agent (the message names the users without an agent and the connectors with no enrollment rows), or no user has finished burn-in yet (the message gives the estimate)For no anchors: install the CLI for an enrolled user, or enroll one. For burn-in: nothing to do
kernel_burn_in_skippedburn_in is 0, so users are enforced without a measured windowSet enterprise.tetragon.burn_in to at least 24h in the admin config to measure first
kernel_policy_operator_override:<family>A policy family was moved to monitor mode or deleted with tetra, and the helper is honoring thatTo hand it back to DefenseClaw, change enforce_ack or mode in the admin config; otherwise leave it as your decision
kernel_policy_not_appliedThe helper runs another control set or mode than the deployment renders, or its last pass did not leave Tetragon with every policy the mode calls for (a recorded policy that is missing after a pass is this warning, not a failure)Wait for the helper's next pass (about a minute). If it stays, run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux ensure so the helper restarts with this build's controls
protected_file_extra_links:<path>A protected file, for example a user's authorized_keys, has a second hard link, which no path control matches. status and verify name the fileRemove the other name (find ~ -samefile <path> finds it)
kernel_link_rename_not_covered:<path>The protected path is not on the root mount, so the link and rename controls leave it out. The open control and the protected-file watch still cover itNone; or move the home onto the root mount
kernel_roots_over_limitMore than four live agent sessions for the monitor controls (see Known limits). The controls do not count the extra sessions' opens, and their users' covered burn-in time pauses until fewer sessions runNone; the count is reported. Burn-in resumes when the extra sessions end
kernel_session_policy_pendingA live agent session's process ID is not yet in an enabled controls policy, so its user accrues no covered time until it is; the covered time measured before staysWait for the helper's next policy pass; if it persists, check Tetragon status and the helper journal for a load failure
kernel_pid_anchor_monitor_onlyIn enforce, an agent session is matched only by its process ID: a script-hosted agent (for example an npm install that node runs), or a session the helper cannot tie to a native agent binary. A process ID can be reused between two passes, so it never denies: the session is monitored and its would-block hits still count. As a user's reason, the user finished burn-in but has no native agent binary to deny throughNone; this is a limit. To have a user denied, install the agent's native binary for that user (see Who a control applies to)
kernel_sessions_predate_controlsIn enforce, the given number of an enforced user's agent sessions started before the controls policy loaded. Tetragon marks an agent's processes when the agent starts, so these sessions are monitored, not denied; status lists them under "Observed, not enforced" (predates_controls). It happens when enforce first loads or after a Tetragon restart, not after a pause and resumeRestart the sessions that predate the controls; new and restarted sessions are denied
kernel_sessions_unconfirmedIn enforce, the given number of an enforced user's agent sessions fit the controls policy, but Tetragon never reported their start on the event stream (the stream was down or the sensor helper restarted before it saw them). They are not counted as denied, their user is armed (kernel_unconfirmed), and status lists them under "Observed, not enforced"Check the stream in status, then restart the sessions while it is connected
no_anchored_sessionA user's reason while armed: enforce is loaded for them, but no running agent session of theirs started from an agent binary after the controls policy loaded, so nothing of theirs is denied at this momentNone; the next agent session they start is denied. If one is running, status lists it under "Observed, not enforced" with the reason
kernel_binary_anchor_scope_limitedMore than one user of a controls policy has a native agent install (in enforce, the users who finished burn-in). The policy denies for one of them, the lowest uid; the other users stay in monitor mode and their would-block hits still count. As a user's reason, another user's native agent holds the deny anchor. With an agent under an administrator prefix (agent_prefixes) every eligible account shares the binary, so the lowest eligible uid holds itThis is a limit (see Who a control applies to). verify --ready-for enforce names the holder; leave accounts that should not hold it out with enterprise.enrollment.exclude_users
kernel_reconcile_failedThe helper's last pass failed to load or update a policy. Policies stay in or move to monitor modeSee the ERROR column of sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux tetragon status and sudo journalctl -u defenseclaw-sensor-helper -n 50
kernel_state_unreadablestatus or verify could not read the helper's state in /var/lib/defenseclaw-sensor, so status shows defaults and no other kernel sensor warning is reportedsudo systemctl restart defenseclaw-sensor-helper. If it persists, check that /var/lib/defenseclaw-sensor is owned by root with mode 0700 and its files are regular files
enrollment_unreadabletargets.yaml cannot be read or is not trusted, so the helper keeps its last enrollmentsudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux repair
tetragon-not-used-per-user (doctor only)A per-user install found Tetragon on the computer; it never connects to it. A skip rowNone

verify fails only for state DefenseClaw owns:

CodeMeaningFix
kernel_policy_orphanedA policy the helper recorded is still loaded in Tetragon while the mode is off or consume, or while the helper is not running, so it keeps enforcing with nobody reconcilingStart the helper with sudo systemctl start defenseclaw-sensor-helper, or remove the policies with sudo /opt/defenseclaw/bin/defenseclaw-sensor-helper --tetragon-cleanup (it refuses while a helper in observe or enforce runs), then run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify. As a last resort, sudo systemctl restart tetragon drops every policy loaded over its API
kernel_policy_load_error:<name>In observe or enforce, with the helper running, Tetragon reports the named DefenseClaw policy in its load-error or error state. A policy that is missing after a pass is the kernel_policy_not_applied warning insteadCheck Tetragon's journal with sudo journalctl -u tetragon -n 50, then sudo systemctl restart defenseclaw-sensor-helper. The helper retries every 5 minutes, and a restart retries at once

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, come after the lifecycle succeeded. In every mdm_ document, installed: false means "not checked". The exit code of each and the full meaning are in Exit codes.

CodeMeaning
mdm_invalid_argumentsA 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_elevatedNot running as root, SYSTEM, or an elevated administrator
mdm_wrong_platformThe Linux copy ran on macOS, or the reverse
mdm_hash_mismatchThe staged source does not match the pinned SHA-256
mdm_signature_invalid, mdm_signer_not_allowed, mdm_signature_unsupportedSignature trust failed, the signer is not allowed, or this source type cannot be checked by signature
mdm_version_mismatchLinux and macOS: the source is not the --product-version you set
mdm_untrusted_inputA config, credential or keyring file can be changed by a non-administrator, or (uninstall.sh) the installed gateway is not root-owned
mdm_untrusted_installWindows, uninstall.ps1: the installed CLI or its folders are not administrator-only
mdm_input_too_largeThe config is over 1 MiB or the credential is over 16 KiB
mdm_payload_invalid, mdm_package_invalid, mdm_wrong_package, mdm_wrong_architectureLinux and macOS: the archive or package is not a DefenseClaw enterprise artifact for this host. The Linux wrapper reads the package architecture, for a .deb and for an RPM, before installation; a package for another CPU architecture reports mdm_wrong_architecture and nothing is installed
mdm_package_manager_busyLinux and macOS: dpkg, rpm or the installer held its lock. Exit 75; retry
mdm_package_install_failed, mdm_package_remove_failed, mdm_package_manager_missingLinux and macOS: the package manager failed or is missing. On macOS, when the package's own preinstall or postinstall refused (a downgrade, a rejected config), the wrapper prints that result instead, with its own code such as downgrade_refused or config_invalid
mdm_package_result_emptymacOS: the Installer failed and the postinstall left an empty last-package-result.json, and no lifecycle run holds the lock. Read last-package-result.log next to it. When a run holds the lock, the wrapper reports lifecycle_busy and exits 75 instead
mdm_disk_fullThe volume of the install root has less free space than the package needs, or the installer ran out of space. Nothing was installed; free some space and rerun
mdm_download_failed, mdm_download_unavailableLinux and macOS: the HTTPS download failed, or there is no curl or wget
mdm_not_installedA read-only action, or an ensure without a source, found no deployment
mdm_binaries_damagedLinux and macOS: an ensure without a source found an installed binary missing, not executable or different from its deployment record. Run the wrapper with the package as the source
mdm_lifecycle_no_result, mdm_lifecycle_launch_failedThe lifecycle did not start or printed no result
mdm_secret_failedStoring the credential failed: on Windows after the deployment applied; on Linux and macOS before the config was applied
mdm_staging_untrusted, mdm_package_incompleteThe private staging folder or the Intune content is not as expected
mdm_staging_noexecLinux: the staging folder is on a noexec mount; pass --staging-dir with a root-only folder that allows execution, or use the deb or rpm
mdm_staging_full, mdm_cancelledLinux and macOS: the staging filesystem filled while extracting a payload; or the MDM stopped the wrapper and its lifecycle child (inspect the deployment before a fresh run)
mdm_base_config_mismatch, mdm_tar_missing, mdm_anchor_install_failedLinux and macOS, signed bundles: the base config does not match the bundle, tar is missing so the comparison cannot run, or the trust anchor file could not be installed.

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

When DefenseClaw refuses a hook call, the agent shows a sentence that names the cause. Some of these sentences end with the code, as the outage codes and the runtime-state codes (enterprise_managed_runtime_descriptor_missing, enterprise_managed_runtime_state_invalid, enterprise_managed_hook_socket_missing, enterprise_machine_policy_summary_untrusted) do; an unenrolled account's does not. For a refusal the gateway made, such as enterprise_managed_uid_unregistered or enterprise_managed_root_denied, the gateway log has the code (journalctl -u defenseclaw-gateway on Linux), and so does the audit log, as the defenseclaw.admin.reason of an api-auth-failure event (sudo /opt/defenseclaw/bin/defenseclaw-gateway audit export, or sudo /opt/cisco/defenseclaw/bin/defenseclaw-gateway audit export on macOS). A code the hook raises itself, such as enterprise_managed_gateway_not_running, is not in the gateway log. The runtime-folder codes apply to per-user-runtime agents. A machine-policy Claude Code hook can recreate a missing user folder and keeps using the machine gateway; a .disabled file in that folder does not disable its machine-policy enforcement. If its trusted state is invalid, it may report enterprise_managed_runtime_state_invalid instead.

CodeOSMeaning and fix
enterprise_managed_uid_unregisteredLinux, macOSThe 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_unregisteredWindowsThe user's SID has no enrolled runtime. Fix: Enroll the user. The guardian writes the user's runtime only while the user has a desktop session (console or Remote Desktop); an SSH, scheduled-task or runas session does not enroll the account
enterprise_managed_enrollment_pendingWindows (standalone)The account has no runtime selected yet: it has not signed in to Windows since it was enrolled, or the guardian revoked its selection (its protected record was rebuilt) and republishes it only in the account's own connected session. Until then the agent is blocked: the hook refuses every tool call, and a signed-out or disconnected session keeps it blocked. Status, verify and the account's own defenseclaw status say blocked until this account signs in or reconnects for an account the guardian enrolled before; an account that was never enrolled sees the enrollment wait text instead. An account used only through runas or a scheduled task never gets that session. Fix: Sign in to Windows once as that user
enterprise_managed_root_deniedLinux, macOSroot called a hook while enrollment.root is deny. Fix: Run the agent as a normal user, or change enrollment.root
enterprise_managed_ledger_unavailableLinux, macOSThe gateway cannot read the guardian's authorization ledger. Fix: Check that the guardian is running, then run reconcile
enterprise_managed_connector_unknownLinux, macOSThe hook call named no connector the gateway recognizes. Fix: Check the hook registration; run reconcile
enterprise_managed_peer_unverifiedLinux, macOSThe 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_unverifiedallThe 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 native hook checks that the socket directory is owned by root or the gateway account and writable only by its owner, then checks that the listener UID reported by the kernel is root or the gateway account. Managed shell hooks and plugins also require the socket itself to be 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_gateway_not_runningallThe gateway service is not running: on Windows the DefenseClawGateway service is stopped; on Linux and macOS the hook socket is missing or nothing accepts on it. The hook denies the call (fail closed; with the administrator's hook_fail_mode: open it allows it and records the failure instead, see Fail modes). The foreign-hook guard narrows this: with foreign_hooks: remove (the default), open applies to the connectors it checks only on Linux and macOS, for an agent process with a current clean-session note; the gateway outage table lists them for each OS. These denials are not in the audit log, because the gateway that writes it is down. The hook gives each one an event ID instead: it writes event_id=<id> to its error output and records the refusal with that event_id in the account's hook-failure log (~/.defenseclaw/logs/hook-failures.jsonl, written only when that folder exists). An account without that folder still gets the ID, with a line saying no local record holds it; the hook never creates the folder. Fix: Run repair, or start the service (systemctl start defenseclaw-gateway-hook.socket defenseclaw-gateway.service on Linux)
enterprise_managed_gateway_restartingLinuxThe gateway service was still stopping or starting about 3 seconds after the hook started (a package upgrade, a rollback, or a configuration or bundle change that needs a restart), so the hook blocked the call. It is never an allow, also with the administrator's hook_fail_mode: open: open covers only a gateway service the hook proves stopped. Fix: None for a restart you started; if it persists, check status and the gateway log
enterprise_managed_gateway_no_answerallThe gateway gave no final decision on a tool call within its answer window (up to about 3.5 seconds from gateway contact, capped at 4 seconds from hook launch). It may have been restarting, being upgraded or repaired, too busy, or its HTTP 429 resends used the window. The hook blocked the call, including with the administrator's hook_fail_mode: open. With foreign_hooks: remove, the guard's session check can block an outage before this deadline too. A decision that waits on Cisco AI Defense or the LLM judge gets up to about 4 seconds from hook launch. Fix: None for a lifecycle run you started; if it persists, check status and the gateway log for a gateway that is slow or stuck
enterprise_managed_hook_socket_selinux_deniedLinuxSELinux kept the user's account from the hook socket: the account is SELinux-confined and the DefenseClaw SELinux module is not loaded (status reports selinux_module_missing). The hook fails closed and tells the user that SELinux is the cause. Fix: Run repair, which loads the module and relabels the socket
enterprise_managed_runtime_descriptor_missingLinux, macOSThe runtime descriptor (managed-runtime.json) is missing. A managed hook invocation denies tool calls even if DefenseClaw's machine-policy entry is gone; Stop and session-end events receive a neutral allow. Fix: Run repair if the deployment should still be installed
enterprise_managed_runtime_state_invalidallThe hook's trusted runtime state is missing or invalid. Fix: Run repair, then reconcile
enterprise_managed_runtime_home_missingall, per-user-runtime agentsThe user's DefenseClaw runtime folder is missing (on Windows, %USERPROFILE%\.defenseclaw was renamed, moved or deleted). The hook tells the user that the folder is missing and to try again in a minute. Fix: The guardian manages this folder and recreates it, on Windows in the account's session, usually within a minute. If the code persists, run reconcile, then read the guardian log
enterprise_managed_runtime_disable_sentinel_forbiddenall, per-user-runtime agentsA .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_blockedallA 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_failedLinux, macOSHermes 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_untrustedallThe hook could not confirm that only administrators can change the machine policy summary it reads or a folder above it: one is not administrator-owned, or (Windows) standard users cannot read the permissions of C:\ProgramData\Cisco, or C:\ProgramData\Cisco\DefenseClaw-HookRuntime lets standard users write it or no longer lets them read it. status and verify fail (machine_policy_summary_untrusted) and name the folder, the account and its access. Fix: Run repair, which writes the hook runtime folder's permissions back (SYSTEM and Administrators full control, BUILTIN\Users read and execute). On Windows it grants BUILTIN\Users read-permissions and traverse on C:\ProgramData\Cisco alone (icacls C:\ProgramData\Cisco /grant *S-1-5-32-545:(S,RC,RA,X) does the same)
enterprise_managed_rate_limitedallHTTP 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). An account runs at most half as many at once as the gateway has processors (at least one), so other accounts keep the other half and are not refused. The hook resends the call a few times within its answer budget. A rate limit is not a classified gateway outage, so if no verdict follows, standalone managed hooks block the call 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
enterprise_managed_overloadedallHTTP 429: the gateway already holds as many hook requests as it can answer in time, across all accounts (16 per processor, at least 32), so it refuses the next one at once. The hook resends the call a few times within its answer budget. A rate limit is not a classified gateway outage, so if no verdict follows, standalone managed hooks block the call whatever hook_fail_mode says. Fix: Retry; the places free up within seconds. If it repeats, the host needs more processors for its peak
HOOK-PAYLOAD-TOO-LARGE (rule ID)allA managed hook, or a per-user hook in the strict policy, refused a prompt or tool call larger than its body cap (1 MiB, fixed on a managed host; in a per-user install DEFENSECLAW_HOOK_MAX_BODY can only lower it) before it reached the gateway. A per-user hook in the default or permissive policy sends the gateway a bounded review instead (Fail modes), unless DEFENSECLAW_HOOK_MAX_BODY lowered its cap under 900 KiB: then it refuses the call too. The user sees "DefenseClaw blocked this prompt: it is too large for DefenseClaw to inspect. Make it smaller and try again." The audit has a hook_decision block with this rule ID and none of the content. Fix: None on the host; the user sends less at once

While a Setup, pkg or rpm run (an install, upgrade, ensure, repair or rollback) holds the gateway stopped, restarting or silent, a managed hook that would block for an outage says "DefenseClaw is being installed or upgraded on this computer, and its gateway is stopped until that run finishes or is recovered. Try again in a moment; if this continues, ask your administrator to check DefenseClaw on this computer: enterprise windows status names what to do." (enterprise linux status or enterprise macos status on those systems), followed by the outage or runtime-state code. Retry after the run ends. A run that was stopped before it finished leaves the same block until it is recovered: status shows transaction_pending and names the recovery. A refusal with its own cause (another program on the port, SELinux, a missing DefenseClaw folder, a bad hook input) keeps its own text. The decision does not change: the call is still blocked.

On Windows, a Setup /repair CONFIG= over a damaged config.yaml on 1.0.6 to 1.0.8 could end 1603 with DefenseClawGateway stopped and transaction_pending. /ensure CONFIG= does not recover that computer. Run, as LocalSystem, from the folder that holds Setup, & '.\DefenseClawSetup-Enterprise-Standalone-x64.exe' /uninstall FORCE=1 JSON=1, then & '.\DefenseClawSetup-Enterprise-Standalone-x64.exe' /ensure 'CONFIG=<approved config>' JSON=1. Setup is not installed on the computer: use the copy in your MDM package or the release download.

Known limits for managed hooks

  • GAP-0409: an unexpected Claude Code policy value type, an untrusted key access list, or server-managed settings can still surface as a slower Setup failure instead of an early policy diagnostic. Setup refuses the policy and keeps the last verified state; inspect the named settings source and correct it before retrying.
  • A managed Claude Code or Codex shell command that has more write targets than the hook can report (more than 512 targets or more than 64 KiB of target paths) is blocked in the strict profile and runs with an alert in the default and permissive profiles. The verdict names rule ACTION-COMPOUND-LIMIT ("Shell command exceeds policy evaluation limit"), the same rule as a call of more than 128 commands (evaluation limit). Split the command into smaller calls. Per-user mode has only the 128-command limit. A protected file among the targets is still found and named, also when the list is longer than the hook can report.
  • On Windows, sustained hook traffic on a disk with slow scattered writes can delay audit writes and hook answers. The gateway checks audit.db-wal every two seconds. From 88 MiB of active log it copies and syncs the log without holding the audit writer until little is left, then holds the writer for up to 180 ms to restart the log (0.12 to 0.18 s in observe mode with a 2 GB audit.db at 10 calls a second). In action mode the log does not settle at that rate, so the holds below apply. If the active log still passes 176 MiB, an ordinary catch-up holds the audit writer for up to 100 ms. At 208 MiB, a flooded log can use one fixed hold of up to 1 second before the 256 MiB ceiling; only the wait to acquire the writer grows after a missed pass, up to 10 seconds. If the file remains over 256 MiB after a check, the gateway warns and repeats the warning every ten minutes while it stays over. A slow disk can still push it past that threshold. In Windows runner tests, the file peaked at 0.9 to 1.2 GB at 10 calls a second; that is an observation, not a disk-space guarantee. A SQLite statement can run past the hold, so some hook answers can still wait seconds or exceed their answer budget. Those calls block under the default closed mode and under an administrator's open too (enterprise_managed_gateway_no_answer): open allows a call only while the hook proves the gateway service is stopped, never a call the gateway took and did not answer in time. Calls of guarded connectors (foreign_hooks: remove) follow open during a proven outage only on Linux and macOS, and only for an agent process the gateway allowed before it stopped (Foreign hook guard); on Windows they block. If the gateway logs a persistent audit WAL over-bound warning, check for a long-running reader and available disk space.
  • A tool call that DefenseClaw allowed while the gateway was running still runs if you approve it in the agent after the gateway stops. Every call checked while the gateway is down is blocked.
  • An upgrade from 1.0.2 or 1.0.3 under hook_fail_mode: open can still let a call of the old hooks run in three cases, only while the upgrade has the gateway stopped (from the stop until the new gateway answers, which the upgrade bounds at 90 seconds before it rolls back):
    • Linux and macOS: an old shell hook that had already started when the upgrade fenced the hooks and was still running 120 seconds later (reported as replaced_hook_calls_running). On Linux it is affected only when the gateway is back later than the hook waits for it (10 seconds; 29 for Copilot CLI and Antigravity).
    • Windows: an old hook process that started before the swap but took more than 30 seconds to start running, and was still running 120 seconds after the swap.
    • Linux, macOS and Windows: an OpenCode or Amp session started under 1.0.2. The plugin runs in the agent, so nothing on disk reaches it; restart the session after the upgrade. 1.0.3 managed plugins already block.
  • On Windows, a program that opens a managed policy file without delete sharing can find it missing while a policy update replaces it, if Windows is slow to finish that atomic replace. The file always holds the old or the new policy. DefenseClaw readers and the Node and Rust agents (Claude Code, Codex, Cursor) open it with delete sharing and never see this. A reader of your own should share delete access or retry a missing file once.

Symptoms

Sandboxes and Tetragon

Sandboxes and Tetragon: Operation not permitted on a Tetragon host, Tetragon not reachable.

Install and MDM

Start with the result document of the failed action (--json, or JSON=1 for the Windows Setup) and look up errors[].code in the code tables. The entries below are the install and upgrade problems that need more than a code lookup.

The first install fails with api_port_held or does not start the gateway

The first managed install fails with api_port_held (Linux and macOS) or not_ready (Windows). A per-user DefenseClaw gateway, or another process, still listens on 127.0.0.1:18970.

Fix. Find the process with the port commands. 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.

Check. enterprise <os> status shows the gateway running.

After a cut-off Windows upgrade, the installed CLI refuses with "module SHA-256 does not match"

An upgrade that a restart, a power loss or a killed Setup cut off leaves files of two releases in C:\Program Files\Cisco\DefenseClaw. Setup copies the installer first, then the module, then the CLI, and records what it copies, so the installed CLI can roll the change back from almost any point. Two short windows remain:

  • the upgrade stopped after it copied the new installer and before the new module;
  • the rollback of that upgrade stopped after it put back the old installer and before the old module.

The installed CLI (enterprise windows status and verify, Remediate-Detect.ps1, Remediate-Fix.ps1 and the Add/Remove Programs uninstall) then refuses with exit 1603. The error says "module SHA-256 does not match the pinned payload manifest". Nothing loads the mismatched files, and the services stay stopped until the change is recovered.

Fix. As LocalSystem, run the Setup of the release you were upgrading to with /ensure (the Intune Win32 app retries it). It brings its own installer and module, rolls the change back and upgrades. See Recover a pending transaction.

Check. enterprise windows status exits 0 and shows the new release.

If the cut-off upgrade had already copied its new module, an Add/Remove Programs uninstall rolls the change back first and then stops: "uninstall rolled back an interrupted lifecycle change and restored the release it replaced; nothing was removed". Run the uninstall again; it uses the restored release's own installer. Earlier than that, the uninstall rolls back and completes.

A Windows ensure with nothing to change takes more than a minute

A Setup /ensure returns noop: true with noop_reason: compliant, but takes 1 to 2 minutes, or up to 5 minutes for the first one after an upgrade. This is expected: each ensure checks the SHA-256 of every scanner runtime file. See No-op ensure time on managed Windows for the measured times.

Fix. None needed. Give the MDM script a time limit of several minutes, and run ensure while agents are idle when you can.

Check. The result has ok: true and noop: true.

The first Windows install stops with preflight_failed naming .defenseclaw

The message names C:\Users\<user>\.defenseclaw, or says "committed, but its protected managed-hook lifecycle journal could not be retired". A per-user install left that folder, and the managed install does not take it over. The first install refuses before it changes anything; a run that had already committed is installed and running.

Fix. Have that user run defenseclaw uninstall --all --binaries --yes, or move the folder out of the profile, then run the same command again. When the message says the change is committed, the installed CLI finishes it: & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' enterprise windows ensure --profile standalone from an elevated PowerShell prompt. See Per-user installs.

Check. The command exits 0.

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.

Fix. Update through your MDM. See Per-user installs.

Check. status shows the new release.

Setup upgrade says another program holds a file open

Setup could not replace the named file while another program had it open. For the installed hook, Setup first gives a program outside the install folder (an antivirus scan, an editor, a backup agent) 30 seconds to close it. If one still holds it, the run stops with hook_in_use and exit 1618 before it replaces anything, and names the program and its process id. hook_calls_running, also exit 1618, means hook calls of the installed release were still running: let those agent calls finish or close those sessions. codex_state_held, also exit 1618, means a user has the Codex state file of 1.0.8 (C:\ProgramData\OpenAI\Codex\.defenseclaw-managed-hooks.state) open without read sharing, so Setup could not carry it into the new release. Setup waits 30 seconds, stops before it changes anything, names the program, and leaves the file as it was. codex_requirements_held, also exit 1618, means a program has C:\ProgramData\OpenAI\Codex\requirements.toml open without read sharing or without delete sharing, or with write or delete access while Setup has to write its access list. A file held like that can neither be read for the snapshot nor replaced, and a run that failed on it after the services stopped could not roll back. Setup treats it like codex_state_held: it waits 30 seconds, stops before it changes anything and names the program. The administrator-edited policy is applied by the guardian once the program lets go.

Fix. Close the program holding it (for example an antivirus or editor), then run the same command again. An MDM retries 1618 on its own.

Check. The command exits 0.

A program holds the hook open and no agent can start it

Every start of defenseclaw-hook.exe fails for every account (a tool call runs unchecked or is blocked, by the connector's fail mode) while a program has the file open in a way that allows no deletion, and the guardian log C:\ProgramData\Cisco\DefenseClaw\logs\guardian\hook-guardian.log has a tamper: line or one of these lines: has the hook open and may be what refuses its starts, found no handle of a user process on it.

The standalone guardian closes that handle by itself when it can, inside bounds: it waits for the second check, when the same program (the same process, or the same file object) still has the hook open, or for the third check when only the same user does in a different process each time (the hook is free 5 to 15 seconds after the hold starts; a single read shorter than about 5 seconds is not closed), closes one handle on the hook's own file at a time, one user at a time, and closes handles only in the processes of a signed-in user. Windows does not show one handle's sharing, so if that user has other handles on the hook, in the same process or another, on the same file object or another, the guardian can close one that was not the cause before it reaches the one that was; it closes no more than it needs to start the hook, and at most 64 handles in one check (if the hook is still refused after 64 it closes the next 64 at a later check, after the wait below). Each close writes a HIGH connector-hook-tampered audit row with the program's path, process id, account, session and the access of the handle. It never closes a handle in a protected process, in a service account's process (LocalSystem, LocalService, NetworkService and the others) or in session 0, and while one of those has the hook open in a way that could refuse the start (it can write, or it is the only file object open on the hook) it closes no user's handle either, because Windows does not show whose handle refuses the start; it logs and audits that hold, names the program and says why it did not close; after about 30 seconds of one user's hold it closes that user's handles once per streak, to rule the program out; a program that only reads, beside another file object, cannot refuse a start and does not stop the close; a handle its owner protected from closing is skipped and the others are closed; if that program is what refuses the start, the hook stays unavailable until it lets go. A row for a hold it did not end has closed set to false; a row waits for the gateway and goes out in order when it answers. A close that finishes after the guardian stopped waiting for it is audited when it finishes. A holder that takes the handle again is closed again after 10 seconds, doubling to 5 minutes.

The guardian also watches the files in C:\ProgramData\Cisco\DefenseClaw-HookRuntime that every hook start reads (machine-policy.json, the closure marker, and each connector folder's enrollment.json and .defenseclaw-managed-runtime-selector.state; never DefenseClaw's own lock files, which Setup and the command line hold on purpose). A program that holds one of them open with no sharing makes every guarded call fail closed; the guardian log then has the hook runtime file ... is held open by another program, so the hook cannot read it, and the guardian ends the hold by the same rules, with an audit row that names the file. On Windows Server 2025 a standard user cannot make such a hold, as measured, because it takes write access to the file; the holders are administrator sessions, SYSTEM and services.

Fix. Find the program in the audit row or the log line (path, process id, account). Stop it, or stop what makes it open the hook (a backup or scan job set to lock files); if it is a service, change its job so that it does not open the hook with no sharing. Nothing else is needed: the hook starts again as soon as the handle is gone.

Check. defenseclaw-hook.exe --version runs, and the guardian log shows no new tamper: line for the hook.

Setup refuses to replace the installed hook

The error says refusing to replace the installed hook and ends Nothing was stopped or changed (exit 1603). The installed defenseclaw-hook.exe does not match the digest in C:\ProgramData\Cisco\DefenseClaw\install\deployment.json (hashes.hook), and the guardian's protected copy, C:\ProgramData\Cisco\DefenseClaw\hook-guardian\payload\defenseclaw-hook.exe, is missing or does not match it either. Before an upgrade Setup keeps a rollback copy of the hook and checks it against that digest; with no matching copy it stops. The new release's /repair does not help: a Setup repairs only its own release and exits 1639. /uninstall refuses with unrecorded artifact hash drift.

Fix. Wait about 5 seconds and run the new Setup again: a running guardian that still has its copy restores the hook itself. If it still refuses, run /repair with the Setup of the release that is installed (the release that installed it, for example 1.0.8, not the new one), as an administrator or as SYSTEM, from the folder with that Setup:

.\DefenseClawSetup-Enterprise-Standalone-x64.exe /repair JSON=1

It puts the hook back to the recorded digest and rebuilds the guardian's copy. Then run the new Setup again. Do not copy defenseclaw-hook.exe out of the release zip by hand: the digest Setup records is that of the hook inside Setup, and the zip's file need not match it (in 1.0.8 it does not), so the new Setup would still refuse.

Check. The new Setup /ensure exits 0.

Setup says the Codex managed-hooks state is not settled

Setup checks the Codex managed-hooks state after it installs, repairs, ensures or upgrades. The Codex writer (the hook guardian or a Setup step) keeps a transaction counter beside the state: odd while it runs, even again when the new state copy is in place. Setup waits, for 30 seconds at most, for an even counter that does not change while it looks. If the counter stays odd, a writer stopped in the middle of a transaction, and the run ends with codex_state_unsettled (exit 1603), the counter value in the message. An install, repair, ensure or upgrade that had started is rolled back (an upgrade returns to the release it came from); a verify changes nothing.

If the writer is a program that is still running and keeps the transaction open, or one that holds the writer lock without moving the counter (an antivirus scanner, a backup program), the rollback cannot judge the Codex state or wait for the guardian's coverage either. It then does what it does for a held file: it leaves the Codex state as it is, starts the restored services, names the writer (process id and account when Windows reports them) and ends with codex_state_unsettled, exit 1618, the transaction still pending and the services running. If the Codex file in place then carries no DefenseClaw hook, the message says so: nothing guards Codex until /repair runs. That run does not prove the guardian's coverage and its result says so; /verify refuses while the transaction is pending, and passes after /repair.

Fix. Stop or end the program the message names (or wait for the next Codex writer pass to end a stopped transaction), then run the command the message names (/repair) as an administrator. It finishes the rollback and exits 0. Never /uninstall FORCE=1 for this.

Check. Setup exits 0 and /verify reports no codex_state_unsettled.

Setup stops a rollback on a Codex file a program holds open

A run that failed after it stopped the services puts the Codex files back from its snapshot. If a program opened requirements.toml (or the Codex state file) after Setup's first check and does not share delete access, Setup cannot put that file back. It waits 30 s for that file to be released, then leaves that one file as it is, puts everything else back and starts the restored services, then ends with codex_requirements_held or codex_state_held (exit 1618). The message names the program and its process id (a program Windows cannot name is described as one that may run as SYSTEM), says to run /repair, and ends with the failure that started the rollback. The transaction stays pending, so the deployment cannot be changed until /repair runs. The four services run and keep enforcing; /verify refuses to run while the transaction is pending. The same applies to the previous hook (hook_in_use) when a program holds the replacement hook open, including the put-back of a recovery that finishes an interrupted run. A file left this way can be out of step with the restored release: a newer requirements.toml beside the older state copy, or the replacement hook (or the closed hook guard) where the previous hook belongs. A Codex agent can then be blocked until /repair runs; that is fail closed by design, not a fault. If the held file is the requirements.toml the recovery had to republish, the result says the guardian's coverage was not proven by that rollback; /verify after /repair proves it.

Fix. Close the program (an editor, a backup or scan job, a user's agent), then run DefenseClawSetup-Enterprise-Standalone-x64.exe /repair CONFIG=<approved config> JSON=1 as LocalSystem. It finishes the rollback and the result shows a normal run. An MDM retries 1618 on its own. /uninstall FORCE=1 is not needed.

Check. Setup exits 0 and transaction_pending is false.

Setup /repair or /ensure replaced a hand-edited Codex requirements.toml

An administrator changed the DefenseClaw part of C:\ProgramData\OpenAI\Codex\requirements.toml by hand (removed a managed hook group, set allow_managed_hooks_only to false) and a later Setup run was interrupted or failed. Recovery used to put that file back and stop at "Codex requirements verify failed", so every /repair and /ensure failed the same way and only /uninstall FORCE=1 cleared it. A /ensure or /repair that finds the edited file in its own Codex step used to fail with 1603, roll back, restore the file and succeed only on the next run; it now replaces the file in that run and exits 0. Recovery publishes the managed policy again, keeps the other settings it can merge, and rebuilds the file from the policy DefenseClaw recorded before it first changed the file when the edit cannot be merged. The result warns codex_requirements_replaced and names the copy of your file: C:\ProgramData\Cisco\DefenseClaw\install\recovered-policy\requirements.toml.hand-edited.<time>.<hash>.bak, byte for byte, readable by Administrators and SYSTEM only.

Fix. Nothing is needed to recover. To keep a setting from the saved copy, put it in the file again after the run (the managed groups and allow_managed_hooks_only = true are DefenseClaw's and are written back by the guardian). A file a program holds open ends the run with codex_requirements_held instead (see above).

Check. /verify exits 0 with no codex_requirements_replaced on the run after.

Setup /ensure exits 1603 while waiting for the hook guardian

Setup waits up to 10 minutes for the guardian's first reconcile while it makes progress. The error says "the hook guardian's first reconcile is still running" or "the hook guardian process" is "no longer running during its first reconcile".

Fix. Read C:\ProgramData\Cisco\DefenseClaw\logs\guardian\hook-guardian.log and C:\ProgramData\Cisco\DefenseClaw\runtime\hook_guardian_startup.json. On a slow device, check antivirus scanning and disk load, then run Setup /ensure again.

Check. The second run exits 0.

An action exits 1618, 75, 1639 or 2

1618 and 75 mean another lifecycle run holds the lock. On Windows, 1618 with hook_in_use, hook_calls_running, codex_state_held or codex_requirements_held means the installed hook or a Codex file is still in use (above). 1639 and 2 mean invalid arguments.

Fix. Retry for 1618 and 75 (Intune retries 1618 by default). For 1639 and 2, fix the command line or the MDM settings; retrying does not help.

Check. The next run exits 0.

A Linux package installed, but nothing runs

The package's postinstall script never fails the package transaction, so a failed lifecycle still leaves the package installed.

Fix. Read /var/lib/defenseclaw-enterprise/last-package-result.json.

Check. After the cause is fixed, ensure --from-package followed by verify passes.

apt or dnf refused an older package

The package's preinstall refuses a downgrade before it replaces any file. The deployed release keeps running.

Fix. For a deliberate downgrade, create the rollback marker first; see Roll back.

Check. The package manager installs the older package.

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.

Fix. 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.

Check. Install the package again; verify passes.

verify says "the installed package is version X but the deployment applied Y"

The package manager replaced the binaries, but the package's own install run failed and rolled back (or an older package was refused), so the record still describes the previous release.

Fix. Read the cause in the message and in last-package-result.json, fix it, and run ensure --from-package. Add --allow-downgrade if X is the older package you meant to go back to.

Check. verify no longer reports a version mismatch.

A release from a mirror is refused

The message says "Releases from <url> are verified by their signature: install cosign 2.0 or later", "The release signature on checksums.txt did not verify" or "refusing a mismatched release". update.source or DEFENSECLAW_REPO points at a mirror. The installers verify every release against the compiled release identity.

Fix. Copy the release files and both checksums.txt and checksums.txt.bundle unchanged, and install cosign 2.0 or later. Or clear update.source (and DEFENSECLAW_REPO). See Where releases come from.

Check. The install verifies the release and proceeds.

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.

Fix. Install first, then store the key. See AI Defense key.

Check. enterprise secret status shows the credential.

systemctl start defenseclaw-hook-guardian.service has no effect

The guardian is always running.

Fix. Run enterprise linux reconcile, or start defenseclaw-hook-guardian-reconcile.service.

Check. verify passes.

Windows Setup refuses "to change the deployment, and nothing was changed"

On a standalone Windows host, Setup /ensure, /repair, /upgrade or /uninstall stops with exit 1603 and the message "refusing to change the deployment, and nothing was changed" (or /verify with "refusing to re-stamp a managed path in place"). Another account owns a managed file or folder, or can change it, for example after icacls <path> /grant Users:(M) or icacls <StateRoot> /reset /T. Setup does not give such a path a trusted access list back, because that account may have changed it. No service was stopped. The message names every refused path (up to 20), the account, and what to do for each.

The hook guardian, and every DefenseClaw step that reads or updates the Claude Code, Codex and Cursor policy folders, do not repair these paths either. That covers those policy folders, DefenseClaw's files in them (the ownership record, the runtime selector, the Cursor rollback receipt), a vendor policy folder that holds a DefenseClaw file, and the folders and files under the DefenseClaw state root (the runtime folder and its tokens, the databases, the secrets folder, the hook guardian's records). Every reader keeps refusing such a path. The guardian log names each one once, with its fix, in one of three lines:

  • machine policy object drift was not repaired: a policy folder or a DefenseClaw file in it.
  • not repaired in place on a standalone install: a folder or file under the state root.
  • hook guardian ledger was not repaired: the hook guardian's authorization folder, protected_targets.json, activation.json or hook_guardian_state.json.

A redaction correlation key another account owns or can change is replaced with a new key instead, so pseudonymised values start over.

Two records Setup can write again are not refused. If another account owns or can change deployment.json or the application-control attestation, /ensure (with the payload) and /repair build the new record next to it with administrator-only access, then swap it in with one atomic step that keeps the changed file next to where it was as <name>.rejected-<UTC time>-<first 12 hex of its SHA-256>, readable by administrators only. A record is in place at every moment, so a crash or a Setup timeout in the middle never leaves the host without one. The new record comes from the machine and the signed Setup payload. The new attestation says "not attested": attest again with enterprise windows repair --attest-agent-application-control, and run the live Claude proof again (/repair ATTESTCLAUDEEFFECTIVEPOLICY=1) if you had recorded one. The installed CLI carries no payload, so its ensure, and status and verify, stop with untrusted_record and name the Setup /repair command and the icacls fix. A folder another account can change is never used for this: it is refused by name. If a program holds the changed file open with write access but allows delete sharing, Setup still replaces the records and finishes the run, but it cannot give the kept copy administrator-only access: it warns, names the kept file and the icacls command, and the next Setup /repair gives the copy its access once the program is stopped (or Windows restarted); an /ensure that finds nothing to repair does not look at it. The kept copy is evidence only and nothing reads it. A program that holds the file open without delete sharing stops Setup before anything changes. If deployment.json is missing and a deployment.json.rejected-* copy is next to it (an earlier build stopped between the two steps), status, verify and install stop with untrusted_record and name that state; run Setup /repair, which writes the record again and never reads the kept copy, or /uninstall PURGE=1 if no gateway service is registered. The other Setup-owned records hold what only they know (the Codex ownership record and access-list backup, the managed-hook journals, the Codex policy file and state) and are refused with the exact command.

If an earlier Setup run stopped with the services stopped, the next run can stop with "refusing to recover the pending lifecycle transaction" instead. The services stay stopped and the transaction stays pending until you fix the paths it names, as below, and run Setup again.

Fix. For each path the message names, from an elevated prompt:

  • A DefenseClaw file in a Claude Code, Codex or Cursor policy folder: delete it, then run Setup /ensure, which writes it new. With the ownership record .defenseclaw-managed-hooks.state, also delete the policy file beside it (90-defenseclaw.json or requirements.toml). For Cursor, delete the record, .defenseclaw-managed-hooks.receipt and defenseclaw-hook.ps1 together. Removing the entry instead is not enough: Setup keeps an unchanged file as it is, and a program that opened it while it could write it can still change it.
  • deployment.json or the application-control attestation (untrusted_record): run Setup /repair (or /ensure, which plans one). The changed file is kept as <name>.rejected-<time>-<hash> and the record is written again.
  • Any other path: remove the account's entry (icacls "<path>" /remove:g *<SID>), or give an owned path back to Administrators (icacls "<path>" /setowner *S-1-5-32-544). Each refusal prints these commands with the real path and account.
  • A writer on the folder above the path (a vendor folder): the refusal names that folder and the account. For Users, Authenticated Users and Everyone it replaces their entry with read and execute (icacls "<folder>" /grant:r "*S-1-5-32-545:(OI)(CI)(RX)"), so standard users can still read the folder; any other account loses its entry (/remove:g). Do not /remove:g Users on a vendor folder.
  • A path that lost its protection and only inherits: do not use icacls "<path>" /inheritance:r on it. On a path that holds only inherited entries it leaves an empty access list, and SYSTEM and the gateway lose access until Setup runs. Run icacls "<path>" /inheritance:d, which keeps copies of the inherited entries, then icacls "<path>" /remove:g *<SID> for the account.
  • A folder Setup cannot list ("Setup cannot list the managed folder"): give Administrators access again (icacls "<path>" /grant *S-1-5-32-544:(OI)(CI)(F)).
  • Check what the file or folder holds, since that account could have changed it.

Then:

  • For config.yaml and targets.yaml, you do not need to fix them by hand: run Setup /ensure CONFIG=<approved config> (add MANIFEST=<approved targets.yaml> in manifest enrollment mode). Setup writes both files new, keeps the old ones as rejected-*.yaml, and publishes fresh approved copies. Without CONFIG=, Setup restores the file from its own approved copy (install\approved-config.yaml, install\approved-targets.yaml) when that copy is current; it keeps the replaced file as rejected-config.yaml or rejected-targets.yaml in the same way and lists it in changes. When no current approved copy exists, the run is refused before any service stops and names CONFIG= or MANIFEST=. A file whose owner or access list another account controls is never given a trusted access list back in place, by Setup or by any command it runs.
  • For a credential or other state you do not keep, Setup /uninstall PURGE=1 deletes it unread. A plain /uninstall keeps the state, so it refuses the same paths.

Check. Run the action again. It names the next paths if more than 20 were refused. /verify JSON=1 passes.

Hooks and policy

Hook refusals show a stable code in the agent's output. Look it up in the hook refusal codes. The entries below are what administrators see on the host.

An agent is not protected at all

Its connector is not a key under guardrail.connectors, or its entry has enabled: false. With no agent enabled, status warns no_connectors_enabled and verify fails.

An entry with enabled: false turns the agent off for DefenseClaw. ensure removes DefenseClaw's hooks and machine policy for it (an administrator's own lines in the vendor file stay). A session that started before the change and still runs the hook gets an allow without a scan. Nothing about the call is kept: no audit row, no export, no copy of the prompt or tool input. The gateway log gets one line per call (enterprise_disabled_connector, with the account's uid, the connector and the route).

These refusals still come first: enrollment.root: deny, a surface refused under unverified_versions: refuse, the require-sandbox refusal (from openshell.admin or the matched profile's sandbox section), and a malformed hook call or one that does not match its hook contract. Root and exempt_users accounts get the same allow without a record. Root is still refused by enrollment.root: deny. Each account keeps only the refusals that already apply to it (root skips the surface check, exempt_users skips the require-sandbox refusal). A session's start gate does not apply: a session whose start was blocked while the agent was enabled gets allows once it is disabled. enrollment.unenrolled_users: deny does not apply to a disabled agent, because DefenseClaw enrolls no account for it.

status lists the agent as disabled on its connectors: line, and in --json as "enabled": false under connectors. An agent listed as not enabled is not in the config (or the config could not be read), but DefenseClaw still has a hook target or found an unprotected install of it.

Fix. Enable the connector under guardrail.connectors and apply the config (Choose the agents to protect).

Check. verify passes.

An agent is not protected on one OS

Its route on that OS is unsupported. OpenClaw and ZeptoClaw are unsupported everywhere.

Fix. Use a supported agent on that OS. See Machine policy.

Check. status lists the agent as protected.

A Cursor Agent CLI prompt disappears with no reply

The gateway service is not running, so the hook refused the prompt. Cursor Agent CLI does not display the refusal for prompts; tool calls show theirs.

Fix. Check the gateway service (enterprise <os> status), start it, or run repair. See Cursor.

Check. The next prompt gets a reply.

Claude Code shows hook error ... ENOENT ... defenseclaw-hook.exe and runs the tool call (Windows)

An antivirus or EDR quarantined C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw-hook.exe. Claude Code treats a hook that cannot start as non-blocking, so tool calls run unchecked until the file is back.

Fix. The hook guardian restores the binary from its protected copy within about 5 seconds; Setup /ensure and /repair restore it too. Exclude C:\Program Files\Cisco\DefenseClaw\bin from quarantine in your EDR policy. See Intune on Windows.

Check. The next Claude Code tool call runs DefenseClaw's hook.

status carries codex_machine_folder_link, cursor_machine_folder_link or claudecode_machine_folder_link, and C:\ProgramData\Cisco\DefenseClaw\logs\guardian\hook-guardian.log has a the <agent> machine folder is a link line that names the link, the cmd /c rmdir fix and the cause (printed again only when it changes). A link, or a file, sits at C:\ProgramData\OpenAI or C:\ProgramData\OpenAI\Codex (Cursor: C:\ProgramData\Cursor; Claude Code: C:\Program Files\ClaudeCode). The guardian never writes through a link. It fails the rows of that agent for every account by name (reparse points are not allowed in Codex machine path), logs each failed row once, and goes on with the other agents: it still revokes stale enrollments and applies the rest. With no account enrolled for the agent there is no row to fail, and the log shows no failure; status still names the link. Removing the link ends it, and an uninstall keeps the link and finishes.

A failure that is not a link still fails the whole pass and is retried: the Codex folder exists but is not trusted, or cannot be recreated. The log then repeats the reconcile failure on each retry. Identical lines are folded: the first one is printed, then a single repeated N more times line when the failure changes, clears, or after 15 minutes. The log is capped at 5 MiB and keeps four earlier generations (hook-guardian.log.1 to .4).

If the Codex folder exists but is not trusted (a standard user created it after the folder was deleted, or its owner or protection changed), the guardian does not take it over. It names the folder once and stays closed for Codex until an administrator runs Setup /repair, which takes the folder over.

Setup /repair, /ensure, /upgrade and /install (a fresh install too) refuse a link on the path of the Codex, Cursor or Claude Code machine-policy folder before they stop anything. They exit 1603 with transaction_pending false and all four services running, and the error names each link and the cmd /c rmdir "<link>" that removes it. Run the same command again once the link is gone.

Fix. As an administrator run cmd /c rmdir "<link>" with the path the warning names. It removes the link and not what the link points to. The guardian recreates the folder within a minute. For an untrusted folder, run Setup /repair.

Check. status no longer lists the warning, and the guardian log has recreated the missing Codex machine-policy folder or a reconcile that passes.

security_complete is false on Windows

Claude Code is enabled and its attestation is not recorded (machine_policy.claudecode without effective_lock: enforce; run the installed CLI's repair --attest-claude-effective-policy from an elevated PowerShell prompt, or Setup /repair ATTESTCLAUDEEFFECTIVEPOLICY=1, again after each upgrade), no Codex, Claude Code or Cursor row is enabled in the target manifest, an enabled agent's hook can let a call run (hook_process_fail_open), an account's Hermes coverage cannot be confirmed (status_detail_unavailable, Hermes NOT COVERED), an account is still pending enrollment, or an enrolled user's Claude Code state cannot be read (claude_state_unreadable).

Fix. Run verify and read every warning: the codes above say why. security_incomplete lists the reasons and names the actionable causes even next to hook_process_fail_open: a Claude Code machine policy that is not verified in force (re-attest after every upgrade with Setup /repair ATTESTCLAUDEEFFECTIVEPOLICY=1), pending or failed per-user enrollments, a guardian that is not ready. hook_process_fail_open (Claude Code, Codex, Copilot, Hermes) and the Hermes status_detail_unavailable warning also keep it false. See Health fields. hook_process_fail_open is a known agent limit: protect the hook process with application control or EDR.

Check. security_complete is true, or false with hook_process_fail_open as its only warning. Coverage and authorization messages name a Windows account as DOMAIN\user (SID) (the bare SID when it does not resolve).

security_complete is false on Linux or macOS

The sensor helper is not running, the run had errors, an agent is agent_unprotected or hook_contract_unverified, a user target is guardian_target_failed, the config enables no agent (no_connectors_enabled), Codex, Claude Code, Copilot, Devin, Hermes, Kiro or Antigravity is enabled (hook_process_fail_open), or on Linux the kernel allows unprivileged user namespaces or process tracing (unprivileged_user_namespaces, unprivileged_ptrace, see Known limits).

Fix. Run verify and read the errors and warnings. hook_process_fail_open is a known agent limit: protect the hook process with application control or EDR.

Check. security_complete is true, or false with only hook_process_fail_open, unprivileged_user_namespaces and unprivileged_ptrace warnings.

An account on a stalled network or FUSE mount

When an agent's home or HERMES_HOME is on a network or FUSE mount that has stopped answering, enterprise linux status/verify (and macos) still answer within a few seconds and report that account as not confirmed. Each run leaves one stat process waiting on that mount until the mount answers or is unmounted.

Fix. Fix or unmount the mount (for example umount -l or fusermount -uz) to clear them.

verify says the Hermes hooks are not verified because HERMES_HOME points elsewhere (Linux and macOS)

An account's persistent environment (an environment.d file, a startup file, or on macOS its launchd environment) sets HERMES_HOME to a home other than the one the DefenseClaw hooks were set up in. verify, readiness and reconcile refuse that account instead of checking the wrong home. Fix. Remove the redirect, or set Hermes up again in the home the account uses, then run reconcile. A value set only in one shell session cannot be seen by the service.

Check. The account is confirmed again and no stat process waits on the mount.

verify fails because of one user (guardian_target_failed)

The guardian cannot repair something in that user's account, for example a config the agent cannot parse or a folder another account owns. A link, non-directory or unreadable folder in the user's home is guardian_target_user_path instead and does not fail verify.

Fix. Read the warning for the user and connector and have the account fixed. See When a user breaks their own setup.

Check. verify passes.

verify fails with verify_failed and machine_policy_incomplete

A higher-precedence policy source outranks DefenseClaw's entry, or your own policy sets a conflicting value.

Fix. enterprise policy show names the source. See Machine policy.

Check. verify passes.

enterprise policy show or verify refuses for a standard account

The policy commands read the managed config, which only administrators can read.

Fix. Run it as root on Linux and macOS, or from an elevated prompt on Windows. See Machine policy status.

Check. The command prints the policy.

policy verify --live refuses

--live needs --user, one --connector (codex or claudecode) and --agent-binary. On a managed Windows host --live is not available.

Fix. Add the missing flags. On Windows use the static verify and confirm with audit export; see Inspect machine policy.

Check. The command runs.

This computer is managed (defenseclaw exits 2)

You see this on Linux: "This computer is managed; use defenseclaw status for your protection state, defenseclaw sandbox status for your sandboxes and defenseclaw sandbox policy explain for your policy. For administrator views, run sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status, sudo /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux verify, or sudo /opt/defenseclaw/bin/defenseclaw-gateway audit export --since 2h. The managed launcher does not offer doctor, alerts, or tui." On macOS it names /opt/cisco/defenseclaw/bin/defenseclaw-gateway and enterprise macos instead of the Linux path and enterprise linux. The command exits 2. On a managed Linux or macOS computer the packaged defenseclaw runs only the commands in Managed command availability; everything else belongs to the administrator.

Fix. Use defenseclaw status to see whether your Claude Code and Cowork are protected, and defenseclaw sandbox ... for sandboxes. An administrator runs /opt/defenseclaw/bin/defenseclaw-gateway enterprise linux status (/opt/cisco/defenseclaw/bin/defenseclaw-gateway enterprise macos status on macOS) as root. Policy changes go in the admin config. On a managed Windows computer a standard account's & 'C:\Program Files\Cisco\DefenseClaw\bin\defenseclaw.exe' status shows the same own state.

Check. defenseclaw sandbox list runs.

A command exits 3 with This device is managed

This is a per-user CLI left from an earlier install. It covers config set, config unset, skill, mcp, plugin and tool block, allow, unblock. The gateway answers 403 managed_device on /enforce/block and /enforce/allow. The host is a managed standalone deployment: its policy comes from the admin config only, so every local writer refuses, even for root. On Linux and macOS each attempt is audited as outcome=refused reason=managed_device. On managed Windows defenseclaw.exe exits 3 and writes no audit row, so check the exit code there. Managed command availability lists which commands a managed computer refuses.

Fix. Make the change in the admin config: asset_policy for block and allow lists, guardrail.block_at for thresholds. See Policy changes on a managed host.

Check. The change applies from the admin config; on Linux and macOS the audit log shows no new managed_device refusal.

A DEFENSECLAW_* variable or .env entry has no effect

The registry marks it ignore on a managed standalone host, so the value is read as unset. DEFENSECLAW_STRICT_AVAILABILITY is tighten_only: honored only when stricter. Managed hooks ignore DEFENSECLAW_HOOK_MAX_BODY and keep the fixed 1 MiB body cap. Hook fail mode comes only from installed policy. DEFENSECLAW_FAIL_MODE in the agent environment has no effect.

Fix. Set the equivalent key in the admin config. See Policy changes on a managed host.

Check. On managed Linux and macOS, doctor is unavailable: the packaged launcher refuses it (Managed command availability). As root, run the installed gateway's enterprise linux status --json or enterprise macos status --json and check that policy.applied is true. The Ignored environment overrides row belongs to the per-user Python CLI.

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.

Fix. Check enterprise secret status and enterprise.network.https_proxy (restart the gateway after changing it). The gateway logs an error from the cisco-inspect subsystem that starts with "standalone managed_enterprise: Cisco AI Defense disabled".

Check. /health shows ai_defense_available; when it is false, ai_defense_error says why.

policy.applied is false

Two messages are possible. "The gateway applies sha256:... but config.yaml and its policy assets compute to sha256:..." means a reload is pending or was rejected, or the file changed under the gateway. "The last change was rejected" (/health has policy.last_reload_error) means the gateway built the new policy generation and rejected it, for example a rule pack or Rego module that no longer loads, or a pinned digest that does not match. It keeps enforcing the previous generation, so nothing is unprotected, but the change is not live.

Fix. Wait one reload, then run status --json again. If it persists, restart the managed gateway or run repair (Restart the managed gateway). For a rejection, read the error, fix the config or the asset it names, and apply the config. A custom rule pack edited in place no longer matches its pinned digest: pin the new digest, or restore the pack. policy digest prints the components.

Check. policy.applied is true in the native lifecycle's status --json. On a per-user install, the equivalent defenseclaw doctor rows are:

[PASS] Policy  —  generation 1, digest sha256:77ef51dce35b (applied by the gateway)
[FAIL] Policy  —  generation 2, digest sha256:0fa3037ac30c is still enforcing: the last change was rejected (config reload rule pack preflight: global rule pack "acme": digest sha256:46ece6be297f9c9b221524923b4baf2035c810503ddfa1b83a1024ee3c55c6e0 does not match guardrail.custom_packs.acme.digest)

Doctor warns "config.yaml was edited outside the DefenseClaw writer"

policy digest may print "config.yaml changed outside the DefenseClaw writer since". config.generation.json does not record the current bytes of config.yaml: someone wrote the file in place. On a managed host the apply trigger runs ensure, which records the edit as the next generation or reverts it.

Fix. Wait for the apply run, or run ensure. If status warns config_rejected, fix the rejected edit. Change the config through your MDM or ensure --config, not by editing the installed file.

In bundle mode (bundle trust anchors installed), the config comes only from signed bundles: a plain config is refused with bundle_required and an edit of the file on Linux and macOS is reverted.

Check. The warning is gone.

Identity and enrollment

An unenrolled user's agent is refused with enterprise_managed_uid_unregistered (Linux, macOS) or enterprise_managed_sid_unregistered (Windows); see the hook refusal codes. After you fix the cause, allow one enumerator cycle (5 minutes) and a guardian reconcile, or run reconcile. The rules are in Enrollment.

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.

Fix. Add the user to enterprise.enrollment.include_users, which bypasses the uid range and the shell check, or change uid_min or uid_max.

Check. The user's agent no longer returns enterprise_managed_uid_unregistered.

A user is not enrolled (Linux and macOS)

The login shell is nologin or false. Or the user is in exclude_users or an excluded group, or in exempt_users (inspected without enrollment). Or the home is outside the allowed home roots (/home and /var/home on Linux, /Users on macOS, plus home_roots).

Fix. Fix the account, the lists or home_roots. See Enrollment.

Check. The user's agent no longer returns enterprise_managed_uid_unregistered.

A user named in include_users is not enrolled (Linux and macOS)

No supported agent is installed in the account. include_users makes the account a candidate, but a row is added only for an agent the enumerator finds installed for that user. This holds for local and directory (mobile) accounts alike. The enumerator log says <user>: named in enterprise.enrollment.include_users but not enrolled: no installation of <agents> found for this account, where <agents> are the per-user connectors.

An account whose only agent is a machine-policy connector (Claude Code, including Claude Desktop and Cowork, on macOS) needs no row: machine policy covers it. The log then says <user>: named in enterprise.enrollment.include_users: no per-user connector install (no <agents> found); covered by machine policy (claudecode), and the cowork block of status lists the account's Claude Desktop installs and engine trust (see Claude Cowork).

Fix. Install the agent in the account (for Hermes, also run its first-run setup), then run reconcile or wait for the next cycle.

Check. status counts one more enrollment target, and the hooks of the user are installed.

A user is not enrolled (macOS)

The uid is below 501.

Fix. Add the user to include_users or set uid_min.

Check. The user's agent no longer returns enterprise_managed_uid_unregistered.

A user is not enrolled (Windows)

One of these holds:

  • The user is in exclude_users or an excluded group, or in exempt_users.
  • 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).
  • The user is signed out or disconnected. The guardian writes hooks only during an active session (console or Remote Desktop); an SSH, scheduled-task or runas session does not enroll the account.

Fix. Have the user sign in, or change the lists. See Enrollment.

Check. The user's agent no longer returns enterprise_managed_enrollment_pending or enterprise_managed_sid_unregistered.

A new user is protected only after a few minutes

The enumerator runs every 5 minutes.

Fix. Wait one cycle, or run reconcile to apply existing rows at once.

Check. The user's agent runs DefenseClaw's hooks.

Find what holds port 18970

Linux
sudo ss -ltnp 'sport = :18970'
macOS
sudo lsof -nP -iTCP:18970 -sTCP:LISTEN
Windows
Get-NetTCPConnection -LocalPort 18970 -State Listen | Select-Object LocalAddress, OwningProcess