Skip to main content

​
Troubleshooting

​
”graft is already initialized”

You tried to run graft init on a container that already has a Graft project. Each container can only be initialized once. 
graft is already initialized for project "my-postgres" at ~/.graft/my-postgres;
remove the project directory to reinitialize
Fix: Delete the project directory and re-init: 
rm -rf ~/.graft/my-postgres
graft init my-postgres --bind

​
“no volumes attached” or “no named volumes found”

The target container must have at least one Docker volume mounted. Database containers typically mount a volume at the data directory. Fix: Ensure your container uses a named Docker volume: 
docker run -v myapp_data:/var/lib/postgresql/data postgres:16

​
Container Not Found

Error: container not found
Fix: Verify the container exists and is spelled correctly: 
docker ps

​
Postgres Fails to Start After Checkout

If Postgres fails to start after switching branches, the data directory may be corrupted or from an incompatible version. Common causes:
  • Switching between different Postgres major versions
  • Manual modification of files in the branch directory
  • Insufficient disk space
Fix: Check the container logs: 
docker logs my-postgres
Try rolling back to a known-good commit: 
graft rollback <known-good-hash>

​
Schema Version Mismatch

state schema version X does not match current Y; delete ~/.graft/<project>/ and re-run graft init
Graft’s schema version changed in an incompatible way between releases. Fix: Delete the project data and re-initialize: 
rm -rf ~/.graft/my-postgres
graft init my-postgres --bind

​
rsync Not Found

Graft uses rsync for the initial Docker-volume-to-host bridge. If it’s not installed: 
rsync binary "rsync" not found
Fix: Install rsync: 
# macOS
brew install rsync

# Ubuntu/Debian
apt-get install rsync

# Verify
rsync --version

​
Docker Not Available

Graft requires the Docker Engine to be accessible via the Docker API. Fix: Ensure Docker is running and the socket is accessible: 
docker ps
On macOS, Docker Desktop creates the socket at ~/.docker/run/docker.sock. Graft auto-discovers this path.

​
Permission Errors on Bind Mount

Database engines run as specific UIDs (Postgres = 999). If bind-mounted files have wrong ownership: Fix: The source files should already have correct permissions (they came from a working container). If you manually copied or modified files, ensure ownership matches: 
chown -R 999:999 ~/.graft/my-postgres/branches/main/

​
“failed to restart container”

The container couldn’t be restarted after a commit or checkout. This is usually a transient Docker issue. Fix: Start the container manually: 
docker start my-postgres
The Graft operation already saved your data — restarting resumes normal operation.

​
Integrity Failure

graft verify reports ✗ Integrity FAILED. This means the files on disk don’t match the Merkle root recorded in the DAG. Common causes:
  • Database was running when files were modified
  • Manual file edits in the branch directory
  • Disk corruption
To investigate: 
# Show exactly which files differ
graft verify --verbose

# Roll back to the previous commit
graft rollback <parent-hash>