> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amulet.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common installation, authentication, mount, and versioning errors.

## `amulet: command not found`

The installer places non-root installs in `~/.local/bin`. Add it to `PATH`, then
open a new shell or run:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
command -v amulet
```

## `AMULET_API_KEY is required`

Export the key in the same shell that runs the CLI:

```bash theme={null}
export AMULET_API_KEY=amulet_...
test -n "$AMULET_API_KEY" && echo "API key is set"
```

If the key was revoked, create a new one in the
[dashboard](https://app.amulet.so/?tab=api-keys).

## The mount fails before it starts

Confirm that the environment is Linux and exposes the FUSE device:

```bash theme={null}
uname -s
test -c /dev/fuse && echo "FUSE is available"
```

Containers and managed sandboxes must explicitly allow FUSE mounts.

## The mount directory is not empty

Amulet refuses to mount over existing files. Choose a new path or move the
existing files elsewhere before mounting:

```bash theme={null}
amulet mount demo ./empty-path
```

## The mount command appears to hang

This is expected: `amulet mount` remains in the foreground for the lifetime of
the mount. Wait for the `mounted` message, keep that process running, and use
another terminal for file operations.

## A snapshot mount is read-only

Snapshots are immutable. Create a writable branch from the snapshot:

```bash theme={null}
amulet mount demo@recovery ./recovery --from-snapshot first-write
```

## A snapshot cannot be found

List snapshots on the same volume or branch used when it was created:

```bash theme={null}
amulet snapshots demo
amulet snapshots demo@experiment
```

Snapshot names are resolved within that volume or branch.

## A branch has different source information

`--from` and `--from-snapshot` apply when a branch is first created. If the
target name already exists with another source, choose a new branch name or
mount the existing branch without source flags.

## Unmounting fails

Pass the exact local mount path:

```bash theme={null}
amulet unmount ./demo
```

If you used an absolute path to mount, use the same path when unmounting. Wait
for the original mount process to exit before mounting at that path again.

## A dashboard volume or usage value is unexpected

API keys are organization-scoped. Switch to the organization that owns the key
and confirm its Volumes and Usage tabs.

For command syntax, run `amulet --help` or see the [CLI reference](/cli-reference).