故障排查

graft sql 提示没有 repository

先在应用数据目录运行：

graft init
graft sql --db data.sqlite "SELECT 1;"

graft sql 需要显式 --db 和已有 .graft/。

数据库没有出现在 status 中

确保 SQLite transaction 已提交，再显式 stage 物理文件：

graft sql --db data.sqlite "INSERT INTO notes(body) VALUES ('hello');"
graft status

外部 SQLite 工具修改后：

sqlite3 data.sqlite "INSERT INTO notes(body) VALUES ('hello');"
graft add data.sqlite

graft add 会捕获已提交的 WAL frames，不需要手动 checkpoint。未提交的 transaction 不属于可暂存状态。

checkout 或 switch 提示数据库正忙

Graft 在替换物理 SQLite 文件前会取得 SQLite 锁、处理 WAL sidecars，并拒绝覆盖 仍有 active writer 的数据库。先提交或回滚 transaction，关闭写连接，再重试 checkout、switch、restore、pull 或 merge-continue。

文件被 external 存储

binary file 总是 external。text file 在超过 files.inline_text_threshold 或 匹配 files.external_paths 时也会 external。

graft config get files.inline_text_threshold
graft config get files.external_paths

clone 或 pull 后 payload 缺失

graft payload status HEAD
graft payload fetch --remote origin HEAD
graft audit --repair origin

pull 进入 merge state

graft status
graft conflicts --json
graft resolve --ours data.sqlite
graft resolve --theirs attachments/report.pdf
graft merge --continue -m "resolve merge"

中止：

graft merge --abort

S3-compatible remote 认证失败

credential 不放在 URI 中：

export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="auto"

R2 或 MinIO 需要 endpoint：

graft remote add origin 's3_compatible://bucket/prefix?endpoint=https://account.r2.cloudflarestorage.com'

HTTP remote 未授权

设置 remote URL 需要的 token environment variable：

export GRAFT_REMOTE_TOKEN='grt_...'
graft ls-remote origin