Skip to main content

​
Run the Built-in Doctor

gc doctor checks your city for structural, config, dependency, and runtime issues. It is always the best first step: 
gc doctor
gc doctor --verbose   # extra detail
gc doctor --fix       # attempt automatic repairs

​
“command not found” After Install

If gc is installed but your shell cannot find it, the binary is not on your PATH. Homebrew puts binaries in a directory that is usually already on your PATH. Run brew --prefix to confirm, then check that $(brew --prefix)/bin appears in your PATH. Direct download requires you to move or symlink the binary into a directory on your PATH: 
install -m 755 gc ~/.local/bin/gc   # or /usr/local/bin/gc
Then verify: 
which gc
gc version
If you use a non-standard shell (fish, nushell), check that shell’s PATH configuration rather than ~/.bashrc or ~/.zshrc.

​
Missing Prerequisites

gc init and gc start check for required tools and report any that are missing. You can also run gc doctor inside an existing city for a fuller check.

​
Always required

ToolmacOSDebian / Ubuntu
tmuxbrew install tmuxapt install tmux
gitbrew install gitapt install git
jqbrew install jqapt install jq
pgrepincludedapt install procps
lsofincludedapt install lsof

​
Required for the default beads provider (bd)

ToolMin versionmacOSLinux
dolt1.86.1brew install doltreleases
bd1.0.0releasesreleases
flock—brew install flockapt install util-linux
If you do not want to install dolt, bd, and flock, switch to the file-based store: 
export GC_BEADS=file
Or add this to your city.toml: 
[beads]
provider = "file"
The file provider is fine for trying Gas City locally. The bd provider adds durable versioned storage and is recommended for real work.

​
Dolt Version Too Old

Gas City requires dolt 1.86.1 or newer. Check your version: 
dolt version
Upgrade via Homebrew (brew upgrade dolt) or download a newer release from dolthub/dolt/releases.

​
bd Version Too Old

Gas City requires bd 1.0.0 or newer. Check your version: 
bd version
Upgrade via Homebrew (brew upgrade beads) or download a newer release from gastownhall/beads/releases.

​
flock Not Found (macOS)

macOS does not ship flock. Install it via Homebrew: 
brew install flock
Alternatively, switch to the file-based beads provider (see above) to skip the flock requirement entirely.

​
gc version Prints Unexpected Output

If gc version prints git progress lines (Enumerating objects...) instead of a clean version string, upgrade to Gas City v0.13.4 or later. This was a bug where remote pack fetches wrote git sideband output to the terminal, fixed in PR #141.

​
WSL (Windows Subsystem for Linux)

Gas City works under WSL 2 with a standard Ubuntu or Debian distribution. Install prerequisites using the Linux column in the tables above. tmux requires a working terminal — use Windows Terminal or another WSL-aware terminal emulator.

​
Build From Source Fails

Building from source requires make and Go 1.25 or newer: 
make --version
go version
If make is missing, install it (apt install make on Debian/Ubuntu, or xcode-select --install on macOS). If your Go version is too old, update it from go.dev/dl or via your package manager. Then: 
make build
./bin/gc version
See CONTRIBUTING.md for the full contributor setup.

​
Still Stuck?

Open an issue at gastownhall/gascity/issues with the output of gc doctor --verbose and your OS/architecture.
Last modified on April 13, 2026