Summary
After upgrading ClawX from v0.4.13 to v0.5.2, the Gateway fails to start. Legacy per-agent memory sidecar files (~/.openclaw/memory/<agentId>.sqlite) that were already migrated into canonical per-agent databases were not renamed to .migrated, causing the OpenClaw 2026.7.1 startup migration to detect row conflicts and block gateway startup.
Steps to Reproduce
- Have ClawX v0.4.13 with existing agent memory data in
~/.openclaw/memory/
- Upgrade to ClawX v0.5.2
- Launch ClawX — Gateway startup fails
Expected Behavior
Gateway starts normally; legacy sidecar files are either auto-archived or the migration handles duplicates gracefully.
Actual Behavior
Gateway startup blocked with fatal error:
legacy memory ... rows conflict with canonical memory index rows
database is locked
openclaw doctor --fix cannot resolve the conflict on its own because the sidecar .sqlite files still exist on disk and trigger the same migration check on retry.
Root Cause Analysis
The canonical per-agent database (~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite) already contains all data from the legacy sidecars (verified by row count comparison). The issue is that the legacy files were never renamed to .migrated after their data was incorporated, so the migration re-detects them as conflicting sources.
Additionally, stale .reindex-lock.sqlite files can cause "database is locked" errors during migration.
Proposed Fix
Add a fallback recovery path in the startup orchestrator:
- Gateway startup fails →
doctor --fix runs (existing behavior)
- If doctor cannot resolve AND stderr shows memory sidecar conflict → automatically archive legacy sidecar files (
.sqlite → .sqlite.migrated) + remove stale lock files
- Retry Gateway startup — succeeds with zero data loss
Environment
- ClawX version: v0.4.13 → v0.5.2
- OS: macOS 15.3 (Apple Silicon)
- Install method: ClawX desktop app
Additional Information
Fix PR: #1208
Summary
After upgrading ClawX from v0.4.13 to v0.5.2, the Gateway fails to start. Legacy per-agent memory sidecar files (
~/.openclaw/memory/<agentId>.sqlite) that were already migrated into canonical per-agent databases were not renamed to.migrated, causing the OpenClaw 2026.7.1 startup migration to detect row conflicts and block gateway startup.Steps to Reproduce
~/.openclaw/memory/Expected Behavior
Gateway starts normally; legacy sidecar files are either auto-archived or the migration handles duplicates gracefully.
Actual Behavior
Gateway startup blocked with fatal error:
openclaw doctor --fixcannot resolve the conflict on its own because the sidecar.sqlitefiles still exist on disk and trigger the same migration check on retry.Root Cause Analysis
The canonical per-agent database (
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite) already contains all data from the legacy sidecars (verified by row count comparison). The issue is that the legacy files were never renamed to.migratedafter their data was incorporated, so the migration re-detects them as conflicting sources.Additionally, stale
.reindex-lock.sqlitefiles can cause "database is locked" errors during migration.Proposed Fix
Add a fallback recovery path in the startup orchestrator:
doctor --fixruns (existing behavior).sqlite→.sqlite.migrated) + remove stale lock filesEnvironment
Additional Information
Fix PR: #1208