rohitg00/agentmemory · warning

[agentmemory] Failed to save index on shutdown:

Error message

[agentmemory] Failed to save index on shutdown:

What it means

On SIGINT/SIGTERM the daemon's shutdown handler stops health monitoring, dedup, persistence scheduling and the viewer server, then makes one final indexPersistence.save() to flush the BM25 index to disk. If that save rejects, the promise's .catch logs this warning; the shutdown continues (sdk.shutdown, pidfile cleanup, exit 0), so the process still exits cleanly but the latest index state may not be persisted. Next startup may need to rebuild the search index from KV.

Source

Thrown at src/index.ts:616

  if (isConsolidationEnabled()) {
    const consolidationTimer = setInterval(async () => {
      try {
        await sdk.trigger({ function_id: "mem::consolidate-pipeline", payload: {} });
      } catch {}
    }, consolidationIntervalMs);
    consolidationTimer.unref();
    bootLog(`Auto-consolidation: enabled (every ${consolidationIntervalMs / 60000}m)`);
  }

  const shutdown = async () => {
    console.log(`\n[agentmemory] Shutting down...`);
    healthMonitor.stop();
    dedupMap.stop();
    indexPersistence.stop();
    await new Promise<void>((resolve) => viewerServer.close(() => resolve()));
    await indexPersistence.save().catch((err) => {
      console.warn(`[agentmemory] Failed to save index on shutdown:`, err);
    });
    await sdk.shutdown();
    clearWorkerPidfile();
    process.exit(0);
  };
  process.on("SIGINT", shutdown);
  process.on("SIGTERM", shutdown);
}

main().catch((err) => {
  console.error(`[agentmemory] Fatal:`, err);
  process.exit(1);
});

View on GitHub (pinned to e04ba88819)

Solutions

1. Check the logged `err` for disk-full (ENOSPC), read-only filesystem (EROFS), or EBUSY and free space / fix permissions.
2. Restart the daemon — on boot the search index is rebuilt/backfilled from KV, recovering any lost persistence.
3. If this fires on every shutdown, ensure indexPersistence.stop() ordering allows save() to run, or upgrade agentmemory where shutdown ordering is fixed.
4. Avoid hard kill (SIGKILL); give the container/process enough shutdown grace period for the final save.

Example fix

// before
await indexPersistence.save().catch((err) => {
  console.warn(`[agentmemory] Failed to save index on shutdown:`, err);
});
// after — retry once before giving up
await indexPersistence.save()
  .catch(() => new Promise((r) => setTimeout(r, 250)))
  .then(() => indexPersistence.save())
  .catch((err) => console.warn(`[agentmemory] Failed to save index on shutdown:`, err));

import fs from 'node:fs';
// before shutdown-critical work, ensure the save target is writable
try { fs.accessSync('./data', fs.constants.W_OK); } catch { console.error('data dir not writable — final save will fail'); }

await indexPersistence.save().catch((err) => {
  console.warn(`[agentmemory] Failed to save index on shutdown:`, err);
  // index is rebuilt from KV on next boot, so no retry storm needed
});

When it happens

Trigger: Raised in the shutdown() handler at src/index.ts:616 when `indexPersistence.save()` rejects — e.g. the state DB was already stopped/closed, the disk is full, or the SQLite write fails during the SIGINT/SIGTERM path.

Common situations: Ctrl+C while a prior write transaction is still in flight; disk-full or read-only filesystem on the host; indexPersistence.stop() having released resources the final save() still needs; container being killed with a short grace period.

Related errors

• [agentmemory] Failed to load persisted index:
• [agentmemory] Failed to backfill memories into BM25:

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/0bed708afae38537. Report an issue: GitHub.