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:

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:

aura doctor --verbose

For a machine-readable report:

aura doctor --format json

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

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:

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:

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):

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

For bash:

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

For 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:

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:

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.

aura status

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

2. The hook file is missing.

ls -la .git/hooks/pre-commit

Should exist and be executable. If it is missing:

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:

aura hooks install --integrate

For a manual integration (for any hook manager):

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

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:

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:

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

Or build from source against your system's libc (see build 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:

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:

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:

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. 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. The #install-help channel is the fastest place to get an answer for environment-specific setup issues.
• Discussions: 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 and write your first intent-logged commit.
• If you are wiring in Claude Code: CLAUDE.md integration.
• If you run a team hub: 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.