# Troubleshooting Install Issues

*The long tail of environment-specific failures, and the tools that diagnose them.*

Most Aura installations succeed on the first try. When they do not, the failure is almost always one of a small set of well-understood issues: a `PATH` that does not include the install location, a hook that did not get installed because Git was not where Aura expected, a tree-sitter grammar that failed to load because of an exotic libc, or a permission error writing to `~/.aura/`. This page walks through those categories in order of frequency, and covers `aura doctor`, the single command you should run any time something feels off.

If your problem is not covered here, the community support channels at the bottom of the page are the next stop.

## First: run `aura doctor`

Any troubleshooting session starts with:

```bash
aura doctor
```

`aura doctor` runs a sequence of environment checks and prints each with a status. A healthy output ends with `All checks passed`. A failing check is printed in red with a remediation hint.

The checks, in rough order:

- Binary is on `PATH` and executable.
- `~/.aura/` exists and is writable.
- Tree-sitter grammars load without error.
- Git is present and >= 2.30 (skipped if not applicable).
- The current repository (if you are in one) has a sane `.aura/` layout.
- Pre-commit hooks are installed and executable.
- `inotify` watch limits are high enough on Linux.
- Mothership session state is consistent with connected teams.

For more detail:

```bash
aura doctor --verbose
```

For a machine-readable report:

```bash
aura doctor --format json
```

`aura doctor` will also attempt to *fix* some issues when invoked with `--repair`:

```bash
aura doctor --repair
```

Repairable issues include: missing hook scripts, orphaned session directories, stale team session keys, and a corrupted parse cache. Non-repairable issues (missing binary, unwritable home) are reported but not touched — those require a human.

## "`aura: command not found`"

The binary is not on your `PATH`. This is the single most common install-day issue.

Check where it actually is:

```bash
ls -la ~/.aura/bin/aura 2>/dev/null
ls -la /opt/homebrew/bin/aura 2>/dev/null
ls -la /usr/local/bin/aura 2>/dev/null
ls -la ~/.cargo/bin/aura 2>/dev/null
```

Exactly one of those should exist. Then check your `PATH`:

```bash
echo "$PATH" | tr ':' '\n'
```

The directory containing the binary must appear in that list. If it does not, add it to your shell profile:

For `zsh` (macOS default):

```bash
echo 'export PATH="$HOME/.aura/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

For `bash`:

```bash
echo 'export PATH="$HOME/.aura/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

For `fish`:

```fish
fish_add_path ~/.aura/bin
```

If you installed via the curl installer and it claimed to edit your profile but did not, check that it edited the right one. The installer picks `~/.zprofile` on macOS and `~/.bashrc` on Linux; if your shell reads a different file, copy the added line over manually.

## "Permission denied" writing to `~/.aura/`

Usually caused by one of:

- Running `aura` as `root` once (under `sudo`), which created files owned by root that a subsequent non-root invocation cannot write.
- A home directory on an NFS or corporate-managed filesystem with restrictive ACLs.
- SELinux or AppArmor confinement.

Fix root-owned files:

```bash
sudo chown -R "$USER:$(id -gn)" ~/.aura
```

For NFS-mounted homes that do not support the needed flock operations, redirect Aura's user directory with an environment variable:

```bash
export AURA_HOME="$HOME/local-aura"
mkdir -p "$AURA_HOME"
```

Add that to your shell profile. Aura will use `$AURA_HOME` instead of `~/.aura/`.

SELinux denials appear in `journalctl` with `avc: denied`. If you see them, file an issue; the maintainers publish a policy snippet for SELinux-enforcing systems.

## Hook not firing on commit

You commit, nothing from Aura runs, the commit goes through unchecked. Several causes are possible:

**1. Aura is not installed in this repository.**

```bash
aura status
```

If this prints "Not an Aura repository" or similar, run `aura init`.

**2. The hook file is missing.**

```bash
ls -la .git/hooks/pre-commit
```

Should exist and be executable. If it is missing:

```bash
aura hooks install
```

**3. Another hook manager replaced the hook.**

Husky, pre-commit.com, and lefthook all manage `.git/hooks/pre-commit` in ways that overwrite whatever was there. Aura knows how to delegate through most of them; tell it to re-register:

```bash
aura hooks install --integrate
```

For a manual integration (for any hook manager):

Add the following line to the hook manager's pre-commit pipeline:

```bash
aura hooks run pre-commit
```

**4. The hook runs, but `aura` is not on the `PATH` the hook sees.**

Shell profile additions (`.zshrc`, `.bashrc`) are not always read by the non-interactive shell Git spawns for hooks. If `aura` runs from your interactive shell but not from the hook, put the binary in a universally-searched directory:

```bash
sudo ln -s "$(which aura)" /usr/local/bin/aura
```

Or edit `~/.aura/bin` into `.git/hooks/pre-commit` explicitly. Run `aura hooks install --repair` to regenerate a hook with an absolute path.

## Tree-sitter grammar failures

An error like:

```
aura: tree-sitter parser for language 'typescript' failed to load
```

Means the bundled grammar dynamic library did not load at runtime. The two common causes:

**1. The binary was built against a glibc newer than what you are running.**

Switch to the static build:

```bash
curl -fsSL https://auravcs.com/install.sh | AURA_STATIC=1 bash
```

Or build from source against your system's libc (see [build from source](/install-from-source)).

**2. Your binary lives on a filesystem mounted `noexec`.**

Some corporate setups mount `/home` with `noexec`. The grammar loader cannot `mmap` from such a mount. Move the binary to `/usr/local/bin` or similar, and set `AURA_GRAMMAR_DIR` to a directory on an `exec`-permitted filesystem.

Run `aura doctor --verbose` for the exact grammar that failed; the error is usually enough to localize the issue.

## Windows-specific: hook runs but does nothing

On Windows, Aura installs a `pre-commit.cmd` wrapper alongside `pre-commit`. Some Git for Windows versions only read the extensionless script and ignore `.cmd`. If your hook is silently skipped:

```powershell
Copy-Item .git\hooks\pre-commit.cmd .git\hooks\pre-commit -Force
```

Or run `aura hooks install --windows-compat`, which handles the wrapper explicitly.

## Mothership connection errors

**"Connection refused"** — the Mothership is not running, or is running but not bound to the expected interface. On the Mothership host, check:

```bash
aura team serve --bind 0.0.0.0:7777   # explicitly bind all interfaces
# or on systemd:
sudo systemctl status aura-mothership
```

`127.0.0.1:7777` binds only locally; remote clients cannot connect. Use `0.0.0.0:7777` for LAN clients.

**"Token expired"** — your join token is past its TTL. Ask for a fresh one.

**"Team ID mismatch"** — the token is for a different team than the repo is already joined to. Run `aura team leave` first, then try joining.

**"Handshake failed: signature invalid"** — the Mothership rejects the handshake. Either the token was tampered with, or the client and Mothership are running protocol versions that cannot negotiate. Upgrade both to the latest release.

**"Sync lag, functions not appearing"** — run `aura live-sync-status` to see the queue state. If your outgoing queue is growing, your client cannot reach the Mothership; check network. If the Mothership sees your push but teammates do not receive it, the Mothership's broadcast is broken — ask whoever runs the hub to check its logs.

## Strict mode lock-out

If strict mode is enabled and `strict_mode_locked: true`, you cannot disable it without the lock passcode. This is deliberate — it prevents an AI agent from disabling its own guardrails.

If you have legitimately lost the passcode, the recovery is:

1. Rotate the team's Mothership state (the lock is enforced through the Mothership's config, not local state).
2. On the Mothership host: `aura team policy unlock --confirm`.
3. The next client sync receives the unlocked policy.

A reminder that strict mode lock is not an access control against malicious actors; it is a friction barrier against well-intentioned mistakes. Someone with root on the Mothership can unlock it.

## "I ran `aura doctor --repair` and it made things worse"

Unlikely but possible. Every `--repair` operation is logged under `~/.aura/doctor-repair.log`. Open an issue with:

- The contents of that log.
- The output of `aura doctor --verbose` from *after* the repair.
- Your OS, Aura version, and which install method you used.

Maintainers can reproduce most `--repair` paths locally given that information.

## Performance issues

**First run is slow.** The first `aura init` parses every source file. In a million-line monorepo that is legitimately slow. Use `--languages <subset>` or set `parse.lazy = true` in `.aura/config.toml` to defer parsing to on-touch.

**Hook is slow on every commit.** The hook should run in well under a second for a typical diff. If it is slower:

```bash
AURA_LOG=debug git commit
```

This prints timing for each stage. Usually the culprit is a large number of unrelated files being re-parsed because the cache got invalidated. `aura doctor --repair` rebuilds the cache.

**Live sync is slow.** The bottleneck is almost always network, not the client. `aura live-sync-status --timing` shows per-function round-trip times. If the Mothership is geographically far from your client, consider a regional Mothership.

## Support channels

When `aura doctor` and this page do not resolve it:

- **GitHub Issues:** [github.com/Naridon-Inc/aura/issues](https://github.com/Naridon-Inc/aura/issues). Search existing issues first; include OS, version, `aura doctor --verbose` output, and exact commands that reproduce the problem.
- **Discord:** the Aura community Discord is linked from [auravcs.com](https://auravcs.com). The `#install-help` channel is the fastest place to get an answer for environment-specific setup issues.
- **Discussions:** [github.com/Naridon-Inc/aura/discussions](https://github.com/Naridon-Inc/aura/discussions) for open-ended questions that are not bug reports.
- **Enterprise support:** if your team is on a paid support plan, your contact channel is in your onboarding email.

When filing a bug, attach:

1. Output of `aura --version`.
2. Output of `aura doctor --verbose`.
3. Your OS and version (`uname -a` on Unix, `winver` on Windows).
4. Exact commands that reproduce the failure.
5. Relevant portions of `~/.aura/aura.log` if Aura crashed.

Do **not** attach raw function bodies or proprietary code. `aura doctor --verbose` scrubs paths and function names by default; double-check before pasting into a public tracker.

## Next steps

- If install is now working: [initialize your first repo](/first-repo) and [write your first intent-logged commit](/first-commit-with-intent).
- If you are wiring in Claude Code: [CLAUDE.md integration](/claude-md-integration).
- If you run a team hub: [Mothership overview](/mothership-overview).

Aura is young enough that the bug you hit might be genuinely new. Filing it helps the project. The maintainers read every issue.