Troubleshooting

Common Issues

"Operation not permitted" after you granted the path

A filesystem entitlement only reaches the kernel if its path exists when the agent starts. Granting a directory you hadn't created yet used to be accepted by the CLI and then dropped when the sandbox profile was sealed — perm said OK, restart said applied, and the write still failed with a bare errno.

mur agent perm allow-read / allow-write now refuse a path that doesn't exist and print the mkdir -p to run. If a dropped grant is already sitting in a profile, mur agent runtime-doctor names it and the fix:

mur agent runtime-doctor        # names grants with no effect, and why
mkdir -p <path>                 # create every granted path that is missing
mur agent restart <agent>

Order matters: create the directory before restarting. Restarting first seals the profile without the grant, and the symptom is identical.

"path not entitled" on a path you did grant

The mirror image of the one above: here the kernel allows the access and the tool refuses it. The symptom is a tool error, not an errno —

path not entitled: /Users/you/.mur/artifacts/shot.png
  (grant it via `mur agent perm allow-read`)

— on a path mur agent perm show lists as granted.

This happened when the grant was written with ~. The sandbox builder expanded it; the in-process tool gate compared the literal string, which never matches. The same gap made a ~/.ssh deny entry inert at the tool layer — the form mur agent doctor suggests — and on Linux that gate is the only place deny-within-allow is enforced at all, because Landlock cannot express it.

Fixed in v2.71.0. If you are on an older build, write grants as absolute paths:

mur agent perm allow-read <agent> /Users/you/.mur/artifacts   # not ~/.mur/...
mur agent restart <agent>

MUR can't create a skill, workflow or fleet

The concierge needs write access to MUR's own authoring dirs under ~/.mur. Fresh installs are seeded with it. An agent seeded by an earlier build is not — an upgrade never widens an existing sandbox. Grant them explicitly, and create any that do not exist yet before restarting:

mur agent perm allow-write mur ~/.mur/skills
mur agent perm allow-write mur ~/.mur/workflows
mur agent perm allow-write mur ~/.mur/fleets
mur agent perm allow-write mur ~/.mur/artifacts
mur agent restart mur

Some paths can never be granted, whatever you ask for. mur agent perm allow-read / allow-write refuse them, and the sandbox denies them in the kernel even if an older profile already carries the grant:

path	refused for
another agent's directory	write — its `profile.yaml` is that agent's entitlements
another agent's `identity.key`	read too — reading it is enough to forge that agent's signed events
`~/.mur/secrets`	read and write — provider API keys and the commander token
`~/.mur/auth.json`	read and write — your account's access and refresh tokens
`~/.mur/identity.key`	read and write — the host signing key
the runtime binary, per-agent symlinks, autostart dirs	write — they run before any sandbox applies

An agent's self-protection covers only its own profile.yaml and identity.key.

~/.mur itself is not on the list. Granting it is accepted, and it is a bad idea: it covers the central stores wholesale. Grant the specific subdirectory an agent actually needs — ~/.mur/artifacts, ~/.mur/skills — and if a broad grant is already in a profile, narrow it rather than relying on the refusals above:

mur agent perm show <name> filesystem       # see what is granted
mur agent perm deny-path <name> ~/.mur/secrets   # deny wins over a grant
mur agent restart <name>                    # entitlements are read at startup

mur agent doctor <name> reports grants whose path does not exist and will be dropped when the sandbox seals.

Patterns not being injected

Check that sync is working: mur sync
Verify your patterns exist: mur stats
Check what would be injected: mur context

Semantic search not working

Ensure you have a search provider configured in ~/.mur/config.yaml
Rebuild the index: mur reindex
For Ollama: make sure the model is pulled (ollama pull qwen3-embedding)
For OpenAI: verify your API key is set

Pattern extraction fails

Check your LLM provider config under learning.llm in config
Verify API keys are set in your environment
Ensure session recordings exist: mur session list

Migrating from v1

If you previously used the Go version (v1):

# Install v2
brew tap mur-run/tap && brew install mur

v2 reads v1 patterns automatically — no migration step required.

Index corrupted

The vector index is fully rebuildable from YAML:

mur reindex

Hooks not firing

If Claude Code hooks aren't triggering:

# Reinstall hooks
mur init --hooks

This updates ~/.claude/settings.json with the necessary hook configuration.

Getting Help

GitHub Issues: github.com/mur-run/mur/issues
Documentation: app.mur.run/docs/core