Background Jobs and Error Log

Published on

Selfhost Podcasting uses background jobs for work that should not slow down the admin screen.

Background jobs are used for:

  • Uploading media to S3-compatible buckets.
  • Deleting uploaded media from buckets.
  • Backfilling missing audio duration.

How Background Jobs Run

The plugin stores a queue in WordPress options and dispatches a non-blocking request to WordPress AJAX on shutdown.

The queue is protected by:

  • A process lock to avoid concurrent runs.
  • Dispatch throttling.
  • Memory checks.
  • Retry limits.
  • Per-podcast upload suspension after repeated terminal upload failures.

Error Log

Find the error log in Selfhost Podcasting > Manage Podcasts > open a podcast > Error Log.

The log stores recent background job errors for that podcast.

Examples:

  • Bucket credentials are missing.
  • Bucket does not exist.
  • Media URL is invalid.
  • Media file is not readable.
  • Upload failed after retries.
  • Duration could not be determined.

The log is capped to avoid database bloat.

Clearing Errors

Use the clear errors action after you have fixed the underlying issue.

Clearing the log does not fix bucket credentials, media URLs, or server connectivity. It only removes stored error records.

Resuming Jobs

If uploads are suspended or dispatch is blocked after repeated errors, use the resume action in the admin.

Before resuming:

  1. Fix the bucket settings or media URL.
  2. Confirm the bucket is reachable.
  3. Confirm the media file exists.
  4. Resume jobs.

Common Causes of Background Job Failures

Site Cannot Make Loopback Requests

Background jobs use WordPress AJAX. Some hosts block loopback requests.

Ask your host to allow WordPress loopback HTTP requests to admin-ajax.php.

Credentials Are Wrong

Re-enter access key, secret key, bucket, region, endpoint, and domain.

WordPress Salts Changed

If salts changed after credentials were saved, encrypted S3 credentials may not decrypt. Re-enter storage settings.

Media File Is Too Large for Server Limits

The plugin supports multipart upload for large files, but the server still needs enough execution time, disk access, and outbound connectivity.

External Media URL Is Blocked

Remote hosts may block HEAD requests, range requests, or downloads. Use a direct media URL that supports standard HTTP access.