# Troubleshoot Edge

Find missing hooks, wrong binaries, environment mismatches, and fail-open events.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/edge/troubleshooting

## Start with diagnostics

```sh
kastra-edge version
kastra-edge status
kastra-edge doctor
kastra-edge doctor --json
kastra-edge config show
```

These inspect the client and configuration. Redact device identifiers and account information before sharing diagnostics outside your team. Never share raw device credentials.

## No decision appears

Check the hook configuration for the actual agent, then restart the agent. Confirm that its process can resolve `kastrahook`, not only that your interactive shell can. Check login, workspace, environment, and connectivity. Hermes also needs its own hook consent.

On macOS, `which -a kastra-edge` and `which -a kastrahook` show competing PATH copies. On Windows, use `Get-Command kastra-edge,kastrahook -All`. Compare each executable's version. Desktop-bundled and package-manager binaries can differ.

## An action proceeded unexpectedly

Look up the exact request or tool-use ID. An ALLOW, an approved HOLD, shadow mode, billing observe-only, and a fail-open event are different explanations. A repeated action may also use the short decision cache, so it may not produce a new backend record.

Inspect the matched rule and the actual attributes. A wrong tool spelling, model prefix, environment, or action predicate can make a rule inert. Use current Windows hooks for shell normalization. Post-action hooks cannot undo a completed action.

## An approval seems stuck

Check the checkpoint state and expiry in the console, the host's timeout, and notification delivery separately. A missing desktop notification does not mean there is no checkpoint. Read [approval lifecycle](https://docs.kastra.ai/approvals/overview) and [failure behavior](https://docs.kastra.ai/reference/failure-behavior).