Skip to main content

Queue Debugging

When to use this runbook​

  • Tasks are accumulating in the queue without being processed
  • The queue processor appears stuck or slow
  • Tasks are failing repeatedly

Step 1: Check processor status​

# Check if the processor is running
ps aux | grep "meduse:queue:processor"

# If not running, restart it
php bin/console meduse:queue:processor --action=runQueues

Step 2: Inspect the queue​

# List pending tasks (SQL-backed)
# Adapt the query to your queue table schema
mysql -e "SELECT COUNT(*), status FROM queue_table GROUP BY status;"

Step 3: Identify failed tasks​

Look for tasks marked as failed:

  • Check associated error messages
  • Identify patterns (same error across multiple tasks?)
  • Review application logs

Step 4: Diagnose the root cause​

Common causes:

SymptomLikely cause
All tasks failingExternal service unavailable (Magento API, carrier)
Repeated deadlocksConcurrency on the same records
Slow tasksUnoptimized query, large data volume
Stuck processorZombie process, unreleased lock

Step 5: Resolve and validate​

  1. Fix the root cause
  2. Restart the processor
  3. Verify that tasks are being consumed normally
  4. If tasks are permanently failed, see Replay Failed Jobs

Ongoing monitoring​

  • Supervise the queue processor with a process manager (systemd, supervisor)
  • Set up alerts on task accumulation
  • Monitor processor error logs