Troubleshooting

Fix daemon, shell hook, policy, cache, and rollback problems with the diagnostics OMG ships for each failure mode.

Start with the built-in diagnostics

First commands to run

omg doctor
omg status
omg --version

Which result points where Read the exit status first, then follow the line that matches it. Change nothing until you know which one you are looking at.

omg doctor checks connectivity, required tools, package-backend health, the daemon, PATH, and the shell hook. Add --network to test mirrors. Add --eol to flag end-of-life runtime versions. Most sections below start from these results.

Daemon problems

Current Linux and macOS release archives include a matching omgd. Archives from v0.1.222 and earlier omit it on non-Arch targets. When no daemon is running, supported package queries use the direct backend path. Use omg daemon-status to inspect the daemon.

Check whether the daemon responds.
```
omg daemon-status
```
Start it if needed.
```
omg daemon
```
Run omgd in the foreground to see startup errors. It removes stale sockets only after ownership checks.
```
omgd
```
If you use a systemd user service, inspect its recent log.
```
journalctl --user -u omgd -n 50
```

Shell hook and completions

Confirm the hook is installed in your profile.
```
grep "omg hook" ~/.zshrc
```

Reinstall it if missing.

echo 'eval "$(omg hook zsh)"' >> ~/.zshrc

Restart the shell completely, not just re-source the profile.
```
exec zsh
```
Test the hook in a project with a version file.
```
omg which node
```

If the prompt feels slow, make sure the daemon is running so the hook avoids the slower fallback path, and prefer the cached prompt functions such as omg-ec over shelling out to full commands. For broken completions, regenerate them and rebuild the Zsh completion cache.

Regenerate completions

omg completions zsh
rm -f ~/.zcompdump && compinit

Search, AUR builds, and policy blocks

Package problems and first fixes

Symptom	Fix
Search returns nothing	Refresh package databases with omg sync, then retry the search
AUR build fails	Install base-devel, clear AUR build directories with omg clean --aur, and retry
Install blocked by policy	Read the rule in the error and inspect the active policy with omg audit policy
Rollback fails	The package cache lacks the old version; fetch it from the distribution archive

On Arch, policy rejections name the violated rule, such as a grade below minimum_grade or a disallowed AUR source. On native APT, DNF, and Homebrew paths, an explicit policy can stop an install because OMG cannot enforce it against the final native transaction. Inspect policy.toml and the active backend before changing either.

AUR build recovery

pacman -Q base-devel
omg clean --aur
omg install <package>

Runtime downloads and switching

When a version will not switch, an older manager often precedes the OMG path. Run which -a node to see every candidate in order. Remove stale PATH entries, run omg use again, then restart the shell with exec zsh.

Download failures are usually network problems. Check proxy variables, connectivity to the runtime origin, and free space in the directory shown by omg config get data_dir. Unsupported runtime names fail by design. OMG does not install a fallback manager for them.

Cache and history corruption

Restart the daemon to clear its in-memory search and package caches.
```
pkill -x omgd; omg daemon
```

If the status snapshot is corrupt, stop the daemon and move the snapshot aside before restarting.

pkill -x omgd; data_dir="$(omg config get data_dir)"; mv "$data_dir/status-cache.json" "$data_dir/status-cache.json.bak"; omg daemon

OMG quarantines a corrupt transaction history automatically. Look for the preserved copy before further recovery.
```
data_dir="$(omg config get data_dir)"; ls "$data_dir"/history.json.corrupt-*
```

Rollback limits

On Arch, official package rollback needs the old archive in the pacman cache. If it is missing, obtain the exact package from a trusted distribution archive, review its provenance, and install the local file explicitly. On Debian or Ubuntu, rollback asks APT to install the recorded package version, which must still be available from configured sources.

Install a downloaded Arch package

omg install ./package.pkg.tar.zst --allow-local-file

Last-resort reset and bug reports

Use a full reset only after targeted recovery fails. Stop the daemon first.
```
pkill -x omgd
```
Print the data directory and review it before moving anything.
```
omg config get data_dir
```
Move the reviewed data directory aside instead of deleting it. On macOS this also moves configuration.
```
data_dir="$(omg config get data_dir)"; mv "$data_dir" "$data_dir.bak"
```
On Linux or WSL, move the separate configuration directory aside.
```
mv ~/.config/omg ~/.config/omg.bak
```
Start the daemon and confirm the clean state.
```
omg daemon && omg status
```

When reporting a problem, include four artifacts. Send the operating system release, omg --version, the output of omg doctor, and the failing command with its error output.