openclaw - 💡(How to fix) Fix [Bug]: Gateway data loss: Silent read error on `paired.json` leads to overwrite of all pairings [1 comments, 2 participants]

A critical data loss bug exists in the OpenClaw Gateway's device and node pairing logic. If paired.json cannot be read on gateway startup for any transient reason (e.g., file lock, temporary I/O error, file corruption), the gateway proceeds with an empty in-memory list of pairings. The next time the state is persisted, this empty list overwrites the valid paired.json file, permanently deleting all existing pairings.

1. Silent Failure in readJsonFile: The utility function readJsonFile (from src/infra/json-files.ts) is designed to catch any and all read/parse errors and return null instead of throwing an error.
2. readJsonFile attempts to read paired.json but fails due to a transient error (e.g., another process holds a temporary lock). It returns null. The error handling in loadState needs to be more nuanced. It should not treat a read/parse failure on an existing file as an empty state. // This is the critical error condition // The gateway should log a severe error and perhaps enter a degraded state throw new Error(Failed to read or parse existing pairing file at ${pairedPath}. Halting to prevent data loss.);

TL;DR

The most likely fix involves modifying the loadState function in src/infra/node-pairing.ts to handle read/parse failures of the paired.json file more robustly, preventing silent data loss.

Guidance

• Check if the paired.json file exists when readJsonFile returns null to differentiate between a non-existent file and a read/parse failure.
• Implement error handling to log a severe error and potentially enter a degraded state if the file exists but cannot be read or parsed, preventing further writes to avoid data loss.
• Review and apply similar fixes to src/infra/device-pairing.ts if it contains the same logic.
• Consider revising the readJsonFile function in src/infra/json-files.ts to throw an error instead of returning null on failure, to make issues more visible.

Example

const paired = await readJsonFile(pairedPath);
if (paired === null) {
  const fileExists = await fs.access(pairedPath).then(() => true).catch(() => false);
  if (fileExists) {
    throw new Error(`Failed to read or parse existing pairing file at ${pairedPath}. Halting to prevent data loss.`);
  }
}
const state = { pairedByNodeId: paired ?? {} };

Notes

This approach focuses on preventing data loss by making read/parse failures visible and handling them appropriately. It does not address the underlying causes of the transient errors (e.g., file locks, I/O errors) but ensures that such errors do not result in permanent data loss.

Recommendation

Apply the workaround by modifying the loadState function as suggested, to prevent data loss and make underlying issues more visible. This approach is preferable because it directly addresses the silent failure issue without requiring changes to other parts of the system.