> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ellomas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions when working with Graft.

# 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.

```text theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
docker run -v myapp_data:/var/lib/postgresql/data postgres:16
```

## Container Not Found

```text theme={null}
Error: container not found
```

**Fix:** Verify the container exists and is spelled correctly:

```bash theme={null}
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:

```bash theme={null}
docker logs my-postgres
```

Try rolling back to a known-good commit:

```bash theme={null}
graft rollback <known-good-hash>
```

## Schema Version Mismatch

```text theme={null}
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:

```bash theme={null}
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:

```text theme={null}
rsync binary "rsync" not found
```

**Fix:** Install rsync:

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:**

```bash theme={null}
# Show exactly which files differ
graft verify --verbose

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