Running and Failures

Change when the daily cleanup runs, run it locally, find a failed cleanup or purge job and replay it.

Changing the Time

The daily run is apps/web/crons/cleanup.ts. Change its cron (UTC, to the minute) to run at a quieter hour:

// apps/web/crons/cleanup.ts
import { cleanup } from '#/config/cleanup.server.ts';
import { defineOutboxSchedule } from '#/lib/outbox.server.ts';
export const cron = '30 4 * * *'; // 04:30 UTC
export default defineOutboxSchedule(cleanup.schedule);

One run a day is enough: each task deletes everything past its window, however much there is. Each run enqueues one cleanup.task job per enabled task, keyed by the run's UTC date (cleanup:<task>:<date>), so a tick Cloudflare delivers twice deletes nothing twice. A cron more often than daily (0 * * * *) adds nothing: later ticks the same day find the day's jobs and enqueue nothing.

A missed tick is skipped, not caught up (Schedules): that day's rows wait for the next run, which deletes them along with its own.

Running It Locally

Crons don't fire in vp dev. Trigger the run with the POST /__void/scheduled command Void prints when the dev server starts (it carries a dev token), with your file's cron (here the default 0 3 * * *; Void matches it exactly):

curl -X POST http://localhost:5173/__void/scheduled \
-H "Content-Type: application/json" \
-H "x-void-dev-trigger: <printed-token>" \
-d '{"cron":"0 3 * * *","scheduledTime":'"$(date +%s000)"'}'

The request enqueues the day's tasks and runs a sweep, which runs them. A second request on the same UTC day enqueues nothing new (existing in the cleanup scheduled log): to run the day's tasks again, replay their jobs (below). Without the token the endpoint answers 401.

Finding Cleanup Jobs

Cleanup and purge jobs are outbox jobs (cleanup.task, cleanup.purge), in outbox.job:

-- today's tasks and how they ended
SELECT dedupe_key, status, last_error_code, terminal_reason, finished_at
FROM outbox.job WHERE kind = 'cleanup.task' AND dedupe_key LIKE 'cleanup:%:' || to_char(now() AT TIME ZONE 'UTC', 'YYYY-MM-DD') || '%'
ORDER BY dedupe_key;
-- purges that gave up
SELECT id, dedupe_key, last_error_code, last_error_message, terminal_reason, finished_at
FROM outbox.job WHERE kind = 'cleanup.purge' AND status IN ('dead', 'cancelled') ORDER BY finished_at DESC;
Statuslast_error_code / terminal_reasonMeans
succeededDone, or handed the rest to a follow-up job (…:<step>)
retrying (dead after 50 tries)code yieldedA batch waited past its 2 s lock timeout (a migration, a long write); it runs again later
retrying / deadcode unexpectedA query failed: a task's (a renamed column, a dropped table), a purge's owner check, or the hand-over enqueue
retrying / deadcode target_failedA purge target failed; the other targets drained. The log has purge target failed with the target and owner id
retrying / deadcode timeoutThe attempt ran past 60 s (a batch far slower than usual: check the index)
deadreason exhaustedOut of retries, with the last code above
cancelledreason unknown_taskThe task was renamed or removed from the config after it was enqueued
cancelledreason disabledThe task was turned off after it was enqueued
cancelledreason owner_existsThe purge found its owner still there and deleted nothing
retrying / deadcode owner_presentA prepared organization purge ran before the delete committed, or the delete failed; it retries while the owner exists

The logs say the same (What Gets Logged), next to the outbox's own failure lines (Failures).

Replaying a Job

Fix the cause first (the table, the column, the config), then replay from server code, never an open route:

import { getOutbox } from '#/lib/outbox.server.ts';
await getOutbox().replay(jobId); // dead or cancelled: runs again with a fresh retry budget

A replayed task or purge picks up where the rows are: it deletes what still matches. Failures has the other operator actions.


Next: Exit Hooks →