Development

How to Schedule and Debug WordPress Cron Jobs

Schedule a WordPress cron job by registering its hook, checking whether the matching event already exists, and scheduling it once. Debug the schedule and callback separately, because an event being present does not prove that its work completed.

WP-Cron is not a promise that work starts at an exact wall-clock second. WordPress checks due work through its scheduling mechanism, commonly triggered by site requests. Low traffic or failed loopback requests can delay execution.

Schedule a WordPress cron job once

Create this complete plugin at sample-cron/sample-cron.php in a disposable WordPress installation:

<?php
/**
 * Plugin Name: Sample Cron
 * Description: Records a periodic housekeeping checkpoint.
 */

defined('ABSPATH') || exit;

/** Registers the recurring event when the plugin is activated. */
function sample_cron_activate(): void
{
    if (!wp_next_scheduled('sample_housekeeping')) {
        $result = wp_schedule_event(
            time() + MINUTE_IN_SECONDS,
            'hourly',
            'sample_housekeeping',
            [],
            true
        );
        if (is_wp_error($result)) {
            wp_die(esc_html($result->get_error_message()));
        }
    }
}
register_activation_hook(__FILE__, 'sample_cron_activate');

/** Records a checkpoint without producing external side effects. */
function sample_cron_run(): void
{
    update_option('sample_last_housekeeping', gmdate('c'), false);
}
add_action('sample_housekeeping', 'sample_cron_run');

/** Removes this plugin's recurring event on deactivation. */
function sample_cron_deactivate(): void
{
    wp_clear_scheduled_hook('sample_housekeeping');
}
register_deactivation_hook(__FILE__, 'sample_cron_deactivate');

The callback records a checkpoint. It deliberately does not send email, charge a card, or perform an unbounded cleanup. Repeating it is inexpensive and does not duplicate a customer-facing action.

The official WP-Cron handbook explains the scheduler. The wp_schedule_event reference documents scheduling arguments and error reporting.

Debug the schedule separately from the work

After activation, use WP-CLI in the target installation:

wp cron event list --fields=hook,next_run_gmt,recurrence
wp cron event run sample_housekeeping
wp option get sample_last_housekeeping
wp cron test

The event list should contain one sample_housekeeping entry. Running the event should update the checkpoint. wp cron test checks the spawning mechanism; it does not validate your callback's business behavior. Consult the WP-CLI cron command reference for the installed command set.

If the event is absent, inspect activation and registration. If it is present but the callback has no effect, inspect hook spelling, plugin loading, PHP errors, permissions, and the callback's own conditions. If manual execution works but automatic execution is delayed, inspect spawning, site traffic, and host configuration.

Keep arguments and event identity consistent

Scheduled arguments participate in identifying an event. Use the same argument array when checking, scheduling, and clearing an event. A mismatch can leave old events behind or create duplicates.

Do not schedule a new recurring event unconditionally on every request. That transforms site traffic into schedule growth. If a plugin changes event arguments in a release, implement a migration that removes the old schedule deliberately.

Design real jobs for interruption and repetition

A production job should process a bounded batch, record its checkpoint, and tolerate retries. If several workers can overlap, use a concurrency mechanism appropriate to the operation. A transient flag by itself should not be advertised as a universally atomic lock.

For external actions, establish an idempotency key or a state transition that prevents duplicate effects. The webhook automation article explains why retries and event identity must be designed together.

If exact scheduling matters, use the host's supported system scheduler to trigger due WordPress work and test the complete path. Merely setting DISABLE_WP_CRON without a working replacement can stop automatic processing.

Should deactivation delete the job's data?

Usually that is a different decision. Deactivation should stop this plugin's scheduled work. Uninstall should follow the product's explicit data-retention policy. Customers may deactivate temporarily while diagnosing a conflict.

For a cron job that affects access, billing, or customer notifications, review scheduling and recovery together.