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>

Overview

CLI Reference

Configuration

Guides

Troubleshooting

Troubleshooting

”graft is already initialized”

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

Container Not Found

Postgres Fails to Start After Checkout

Schema Version Mismatch

rsync Not Found

Docker Not Available

Permission Errors on Bind Mount

“failed to restart container”

Integrity Failure

​Troubleshooting

​”graft is already initialized”

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

​Container Not Found

​Postgres Fails to Start After Checkout

​Schema Version Mismatch

​rsync Not Found

​Docker Not Available

​Permission Errors on Bind Mount

​“failed to restart container”

​Integrity Failure

Troubleshooting

”graft is already initialized”

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

Container Not Found

Postgres Fails to Start After Checkout

Schema Version Mismatch

rsync Not Found

Docker Not Available

Permission Errors on Bind Mount

“failed to restart container”

Integrity Failure