beads/website/versioned_docs/version-1.0.0/reference/troubleshooting.md
matt wilkie e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
2026-04-25 11:30:19 -07:00

225 lines
2.8 KiB
Markdown

---
id: troubleshooting
title: Troubleshooting
sidebar_position: 4
---
# Troubleshooting
Common issues and solutions.
## Installation Issues
### `bd: command not found`
```bash
# Check if installed
which bd
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
# Add Go bin to PATH
export PATH="$PATH:$(go env GOPATH)/bin"
# Or reinstall with the recommended installer
curl -fsSL https://raw.githubusercontent.com/gastownhall/beads/main/scripts/install.sh | bash
```
### `zsh: killed bd` on macOS
CGO/SQLite compatibility issue:
```bash
CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install github.com/steveyegge/beads/cmd/bd@latest
```
### Permission denied
```bash
chmod +x $(which bd)
```
## Database Issues
### Database not found
```bash
# Initialize beads
bd init --quiet
# Or specify database
bd --db .beads/beads.db list
```
### Database locked
```bash
# Stop the Dolt server if running
bd dolt stop
# Try again
bd list
```
### Corrupted database
```bash
# Check and fix database
bd doctor --fix
# Or pull from Dolt remote
bd dolt pull
# Or restore from a backup
bd backup restore [path] --force
```
## Dolt Server Issues
### Server not starting
```bash
# Check server health
bd doctor
# Check server logs
cat .beads/dolt/sql-server.log
# Restart the server
bd dolt stop
bd dolt start
```
### Version mismatch
After upgrading bd:
```bash
bd dolt stop
bd dolt start
```
## Sync Issues
### Changes not syncing
```bash
# Force push to Dolt remote
bd dolt push
# Check hooks
bd hooks status
```
### Recovery from backup
```bash
# Restore from a Dolt backup
bd backup restore [path] --force
# Or pull from Dolt remote
bd dolt pull
```
### Merge conflicts
```bash
# Check for and fix Dolt conflicts
bd doctor --fix
# Re-push
bd dolt push
```
## Git Hook Issues
### Hooks not running
```bash
# Check if installed
ls -la .git/hooks/
# Reinstall
bd hooks install
```
### Hook errors
```bash
# Check hook script
cat .git/hooks/pre-commit
# Run manually
.git/hooks/pre-commit
```
## Dependency Issues
### Circular dependencies
```bash
# Detect cycles
bd dep cycles
# Remove one dependency
bd dep remove bd-A bd-B
```
### Missing dependencies
```bash
# Check orphan handling
bd config get import.orphan_handling
# Allow orphans
bd config set import.orphan_handling allow
```
## Performance Issues
### Slow queries
```bash
# Check database size
ls -lh .beads/beads.db
# Compact if large
bd admin compact --analyze
```
### High memory usage
```bash
# Reduce cache
bd config set database.cache_size 1000
```
## Getting Help
### Debug output
```bash
bd --verbose list
```
### Logs
```bash
cat .beads/dolt/sql-server.log
```
### System info
```bash
bd info --json
```
### File an issue
```bash
# Include this info
bd version
bd info --json
uname -a
```
Report at: https://github.com/gastownhall/beads/issues