# Running and Failures

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

*Canonical: https://makerkit.dev/docs/void-cloudflare/cleanup/running*

---

## 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:

```ts
// 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](../outbox/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):

```bash
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`:

```sql
-- 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;
```

| Status | `last_error_code` / `terminal_reason` | Means |
|---|---|---|
| `succeeded` | | Done, or handed the rest to a follow-up job (`…:<step>`) |
| `retrying` (`dead` after 50 tries) | code `yielded` | A batch waited past its 2 s lock timeout (a migration, a long write); it runs again later |
| `retrying` / `dead` | code `unexpected` | A query failed: a task's (a renamed column, a dropped table), a purge's owner check, or the hand-over enqueue |
| `retrying` / `dead` | code `target_failed` | A purge target failed; the other targets drained. The log has `purge target failed` with the target and owner id |
| `retrying` / `dead` | code `timeout` | The attempt ran past 60 s (a batch far slower than usual: check the index) |
| `dead` | reason `exhausted` | Out of retries, with the last code above |
| `cancelled` | reason `unknown_task` | The task was renamed or removed from the config after it was enqueued |
| `cancelled` | reason `disabled` | The task was turned off after it was enqueued |
| `cancelled` | reason `owner_exists` | The purge found its owner still there and deleted nothing |
| `retrying` / `dead` | code `owner_present` | A 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](./overview#what-gets-logged)), next to the outbox's own failure lines ([Failures](../outbox/failures)).

## Replaying a Job

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

```ts
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](../outbox/failures#replay-and-cancel) has the other operator actions.

---

**Next:** [Exit Hooks →](./exit-hooks)
