Common errors

The error messages Agent Guard surfaces most often, what they mean, and how to fix them. Organized by the part of the system that failed.

Install and first run

agentguard: command not found

The install script either failed or installed the binary somewhere not on your PATH. Check both:

ls -l /usr/local/bin/agentguard
echo $PATH | tr ':' '\n' | grep /usr/local/bin

If the binary is present but /usr/local/bin is not in your PATH, add it to your shell profile. If the binary is missing, re-run the install script and watch its output for the actual failure.

Rootfs extraction failed on first run

The first agentguard run extracts a ~500MB Debian rootfs from the Agent Guard binary into ~/.agentguard/vm/. No network call is involved; the rootfs ships inside the binary. The usual cause of a failure here is:

• Disk full. The image needs ~500MB free in ~/.agentguard/vm/. Check with df -h ~.

After freeing up space, delete any partial file with rm ~/.agentguard/vm/rootfs.img* and re-run.

unsupported platform

Agent Guard requires macOS on Apple Silicon. Intel Macs and Linux are not supported in this release. Windows support is on the roadmap.

To confirm your platform:

uname -m   # Should print "arm64"
sw_vers    # Should print macOS, not Linux or Windows

MicroVM boot

VM failed to start: virtualization permission denied

Agent Guard uses Apple's Virtualization.framework. macOS requires the binary to be signed with the right entitlements. The install script handles this for release binaries, but locally built binaries need make sign-devid or equivalent.

If you installed via the official script and still hit this, check Console.app for entitlement-related errors around the time the run failed. Re-running the install script forces a re-signature.

init: mount /dev/vda failed

The rootfs image is corrupt or the wrong version for your binary. Force a clean re-extraction:

rm ~/.agentguard/vm/rootfs.img ~/.agentguard/vm/rootfs.version
agentguard run claude-code --workspace ~/projects/myapp

If the failure repeats, capture ~/.agentguard/vm/serial.log and file an issue at the GitHub repo.

VM timed out waiting for guest agent

The microVM booted but the guest-side hook handler did not come up in time. Usually one of:

• Memory pressure. macOS swapped the microVM out and it could not respond. Free memory and try again, or lower --ram if your machine is small.
• Stale environment. A previous run left the overlay in a bad state. Try agentguard env delete <name> to start fresh.
• virtiofs issue. If your macOS version has known virtiofs problems, fall back to vsock transfer with --no-live-sync.

Policy sync

policy add: registry returned 401 Unauthorized

The registry requires authentication and you have not provided credentials. Pass -u and -p on policy add:

agentguard policy add hub.acme.com/sec-team/policies:v3 \
  -u deploy-bot \
  -p "$REGISTRY_TOKEN"

For tokens stored in the macOS Keychain or a password manager, look up the value before running and pass it inline.

policy add: registry returned 404 Not Found

The ref does not exist. Two common shapes for this error:

• Wrong tag: the ref acme/policies:v3 exists but the tag is :v4. List tags from the registry UI or kit list-tags.
• Wrong path: typos in the repository path. agentguard policy add does not auto-correct.

policy add: signature verification failed

You passed --pub-key (or have a trusted key configured) and the artifact's cosign signature does not verify against any trusted key. Either:

• The artifact was not signed by the team that owns the trusted key.
• The artifact was tampered with in transit.
• You are using a stale public key. Refresh the key from the publisher and re-add.

Agent Guard fails closed here on purpose. The previously cached version of the policy (if any) stays in place; nothing is overwritten with an unverifiable artifact.

sync error: connection refused

Agent Guard could not reach the registry. Check connectivity (curl -I https://<registry-host>), proxy configuration, and DNS. If you are intentionally working offline, use --no-sync on agentguard run or set AGENTGUARD_NO_SYNC=1.

Policy evaluation

policy block: tool=<X> rule=<Y>

Not an error. The agent tried to do something the policy blocks. The audit log captures the full context. To allow the action, either modify the policy or use a different policy tier.

If you wrote the policy and the block is unexpected, run the agent with --verbose and check the policy server log:

tail -f ~/Library/Logs/AgentGuard/policy_server.log

policy evaluation error: failed to parse CEL

A CEL assertion in one of your policies is malformed. The log line names the policy file and the specific line. Common causes:

• Unquoted false (YAML parses it as a boolean before CEL ever sees it). Wrap in quotes: assert: "false".
• Missing orValue("") on a field that is not always present. CEL throws on missing field access.
• Mismatched parentheses across multiple lines of CEL.

Fix the file, save, re-run. There is no separate compile step; Agent Guard re-parses on every run.

policy evaluation error: server unreachable

The in-VM Agent Guard AI Gateway is not responding on 127.0.0.1:9091. This is fail-closed, so the tool call is blocked. Check the policy server log:

cat ~/Library/Logs/AgentGuard/policy_server.log

If the server crashed during boot, the log will show why. Common causes are policy parse errors that crashed the server on startup; fix the offending policy and re-run.

Credentials and agent auth

claude-code: authentication failed

The cached OAuth token expired or was revoked. Force re-authentication by deleting the cached entry:

security delete-generic-password -s AgentGuard -a vm-claude-code-credentials

The next agentguard run claude-code will prompt for the OAuth flow again.

To use an API key instead of OAuth, set ANTHROPIC_API_KEY before running.

gemini: account is logged out

Gemini CLI's credentials must be created on the host first. Run on the host:

npm install -g @google/gemini-cli
gemini login

Agent Guard copies the resulting credentials into the microVM on next run.

--pass-env <KEY>: variable not set

You asked Agent Guard to pass a host environment variable but it was not set in your shell. Set it before running:

export GH_TOKEN=$(gh auth token)
agentguard run claude-code --pass-env GH_TOKEN --workspace ~/projects/myapp

If the variable is set in a different shell, source the file that sets it or move the export to your shell profile.

--pass-cloud-creds aws: no AWS credentials found

The flag passes credentials from environment variables (and from the credentials file pointed at by AWS_SHARED_CREDENTIALS_FILE). If neither is set, there is nothing to pass.

Set credentials via aws sso login, aws sts assume-role, or by exporting AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY before running.

Workspace and file access

workspace not found: <path>

The path passed to --workspace does not exist. Check the path; remember that ~ is expanded by the shell, not by Agent Guard, so quoting the argument can change behavior.

agent reports: permission denied: /workspace/<file>

The agent is running inside the microVM. /workspace/ is the live mount of your host workspace. A permission denied here usually means one of:

• The file's host-side permissions don't allow read or write by your user.
• The file is in a location outside the mounted workspace (the agent can't reach anything else).
• A policy is blocking the operation. Check the audit log to confirm.

virtiofs: cannot mount workspace

The macOS virtiofs implementation has known issues with certain workspace setups (network shares, some external drives). Fall back to vsock tar transfer:

agentguard run claude-code --no-live-sync --workspace ~/projects/myapp

Workspace changes are copied in once at startup and copied back on exit. This is slower for large workspaces but works around virtiofs failures.

Environments

env delete: environment not found

The environment name does not match anything in ~/.agentguard/vm/environments/. List what exists:

agentguard env list

Auto-generated environment names are <agent>-<sha256(workspace)[:12]>. If you don't know the name, use agentguard env list --agent claude to filter.

env fork: source environment is in use

Cannot fork an environment that has a live microVM session. Exit the running session first, then fork.

out of disk space

Each environment holds overlay state for installed packages and tool configs. After many runs across many workspaces, these accumulate.

Show per-environment disk usage:

agentguard env list

Delete environments you no longer need:

agentguard env delete <name>

Agent definitions

framework mismatch: definition says claude-code, run says <agent>

The positional argument to agentguard run and the framework: field in the agent definition disagree. Either change the run command to match the definition, or update the definition's framework: field.

auth.key references env.<VAR>: variable not set on host

The agent definition references an environment variable (e.g., auth.key: env.ANTHROPIC_API_KEY) that is not set in your shell when Agent Guard resolves the definition. Either set the variable before running, or remove the auth: block to fall back to the agent's own OAuth flow.

pull blocked by ArtifactPolicy: registry not trusted

An MCP module or policy module in the definition points at a registry that is not allowed by the loaded ArtifactPolicy. The default trust policy only allows jozu.ml. To allow others, load an ArtifactPolicy that matches the additional registry. See Policy schema reference for the pattern.

agent-ref: artifact not found in local kit store

kit pack succeeded in one shell but agentguard run --agent-ref cannot find the artifact in another. The two shells likely have different KITOPS_HOME settings, so they point at different local stores. Run kit list in the same shell you intend to run Agent Guard from to confirm visibility.

Uninstall

uninstall: cannot remove ~/.agentguard while VM is running

A microVM session is still running. Find and exit it first:

agentguard top

Or kill the session directly if the agent is unresponsive:

ls ~/.agentguard/sessions/   # Shows <pid>.json files
kill <pid>

Then re-run agentguard uninstall.

Reporting issues

If a failure isn't listed here, file an issue at github.com/jozu-ai/agentguard/issues. Include:

• Agent Guard version: agentguard --version
• macOS version: sw_vers
• The exact command that failed
• Relevant log excerpts from ~/Library/Logs/AgentGuard/ and ~/.agentguard/vm/serial.log
• The smallest policy file that reproduces a policy-related issue