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