What causes "Cleanup preview generation failed" in odysseus-dev/odysseus?

Read the server log for the 'Cleanup preview failed' line — the underlying exception names the real problem.

odysseus-dev/odysseus · error · HTTPException

Cleanup preview generation failed

Error message

Cleanup preview generation failed

What it means

Raised as HTTP 500 by the cleanup preview endpoint when get_cleanup_preview(owner=user) throws any exception; the original exception is logged via logger.error before re-raising. It is a catch-all: the 500 tells you only that computing the dry-run preview failed, and the real cause is in the server log line 'Cleanup preview failed: <e>'.

Source

Thrown at routes/cleanup/cleanup_routes.py:36

        APIRouter instance with cleanup routes
    """
    router = APIRouter(prefix="/api/cleanup")

    @router.get("/preview")
    async def cleanup_preview(request: Request):
        """
        Preview what would be cleaned up without making any changes.

        Returns:
            JSON response with lists of sessions that would be archived/deleted and estimated space savings
        """
        user = get_current_user(request)
        try:
            preview = await get_cleanup_preview(owner=user)
            return preview
        except Exception as e:
            logger.error(f"Cleanup preview failed: {e}")
            raise HTTPException(500, "Cleanup preview generation failed")

    @router.post("")
    async def cleanup_endpoint(request: Request):
        """
        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)

View on GitHub (pinned to f9235ebbf1)

Solutions

Read the server log for the 'Cleanup preview failed' line — the underlying exception names the real problem.
Verify the server process has read access to the sessions storage directory and its files.
Remove or restore the corrupt session artifact the scan is choking on (often visible in the traceback path).
Free disk space if the error is an OSError during size/stat computation.

Defensive patterns

Strategy: try-catch

Validate before calling

const resp = await fetch('/api/cleanup/preview');
if (resp.status === 500) {
  console.error('Preview failed — check server log for "Cleanup preview failed"');
  return null; // degrade gracefully, do not offer cleanup
}

Try / catch

try {
  preview = await api.getCleanupPreview();
} catch (e) {
  if (e.status === 500) { notify('Could not compute cleanup preview'); return; }
  throw e;
}

Prevention

Always run the preview endpoint before the mutating cleanup POST — it doubles as a health check.
Keep the sessions data directory readable by the service user and monitor disk space.
Correlate every 500 from these routes with the logged 'Cleanup preview failed' line to reach root cause.

When it happens

Trigger: GET of the cleanup preview endpoint when the sessions directory is unreadable/deleted, session metadata is corrupt, disk stats fail, or the owner filter hits an unexpected state while scanning sessions.

Common situations: Sessions data dir moved or permission changed after a manual migration; a partially-written session file from an unclean shutdown; running as a different OS user than the one owning the data directory; disk-full conditions during stat() calls.

Related errors

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