What causes "Cleanup operation failed" in odysseus-dev/odysseus?

Check server logs for the 'Cleanup failed' entry to identify the failing phase (archive vs delete).

odysseus-dev/odysseus · error · HTTPException

Cleanup operation failed

Error message

Cleanup operation failed

What it means

Raised as HTTP 500 by the POST cleanup endpoint when cleanup_sessions(session_manager, owner=user) throws; the cause is logged as 'Cleanup failed: <e>' first. Unlike the preview, this endpoint mutates state, so a 500 may mean the operation failed partway — some sessions may already be archived/deleted before the exception.

Source

Thrown at routes/cleanup/cleanup_routes.py:58

        """
        Perform cleanup operations:
        1. Archive inactive sessions (not accessed for 7 days)
        2. Delete old sessions (archived, not important, not accessed for 14+ days, with fewer than 10 messages)

        Returns:
            JSON response with counts of deleted and archived sessions, and space freed
        """
        user = get_current_user(request)
        try:
            archived_count, deleted_count, space_freed_mb = await cleanup_sessions(session_manager, owner=user)
            return {
                "archived_count": archived_count,
                "deleted_count": deleted_count,
                "space_freed_mb": round(space_freed_mb, 2)
            }
        except Exception as e:
            logger.error(f"Cleanup failed: {e}")
            raise HTTPException(500, "Cleanup operation failed")

    return router

View on GitHub (pinned to f9235ebbf1)

Solutions

Check server logs for the 'Cleanup failed' entry to identify the failing phase (archive vs delete).
Fix filesystem permissions on the sessions directory so the server user can move/delete files.
Re-run the preview endpoint afterwards and reconcile counts — partial completion is possible; a second POST is idempotent for already-archived sessions.
Ensure only one cleanup runs at a time (avoid double-clicking / parallel schedulers).

Defensive patterns

Strategy: try-catch

Validate before calling

const preview = await fetch('/api/cleanup/preview');
if (!preview.ok) { /* do not run destructive cleanup when preview fails */ }

Try / catch

try {
  result = await api.runCleanup();
} catch (e) {
  if (e.status === 500) {
    const p = await api.getCleanupPreview(); // reconcile partial completion
    report('Cleanup failed partway', p);
    return;
  }
  throw e;
}

Prevention

Gate the destructive POST on a successful preview response.
Run only one cleanup at a time; disable double-submit in the UI.
After any 500, re-run preview to reconcile counts because archive/delete may have partially applied.

When it happens

Trigger: POSTing the cleanup endpoint when archive/delete operations fail: file permission errors deleting session dirs, DB errors updating archived flags, or an unexpected session object shape mid-iteration.

Common situations: Read-only or root-owned session files after restoring from backup; concurrent cleanup runs racing on the same sessions; DB locked by another writer; the preview succeeded but disk filled between preview and execution.

Related errors

AI-assisted analysis of odysseus-dev/odysseus@f9235ebbf1 (2026-08-14). Data as JSON: /api/errors/a998175cc2f8a61f. Report an issue: GitHub.