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: Identify the queue and consumer

Start with the operation's producer and persisted work item. The word “Meduse” does not identify a single queue.

Work item	Follow this implementation
Logidav general SQL queue (mz_queue)	Queue model and the producer's workflow
Logidav dedicated Meduse SQL queue (mz_meduse_queue)	Meduse integration contract
Meduse Laravel dispatch/job	Meduse queues and processors
FTP file state: pending, processing, complete or failed	Meduse file handoffs
Mosaikasa Shopify bulk worklist	Application worklists

In the reviewed Logidav revision, QueueService::addQueue() forces its Meduse-queue option off. meduse:queue:processor selects pending dedicated-queue models and executes them; it is not a generic health check or a Meduse Laravel worker. Its absence from a process list alone does not show that a required processor is down.

Confirm the deployed revision, configured queue/connection, producer and intended consumer before selecting a diagnostic or recovery command. This guide does not establish the current process supervisor or active worker configuration.

Step 2: Inspect the matching state

For an approved environment, correlate the same product/operation identifier across the producer record, queue or file state, consumer result and destination acknowledgement. Check the actual entity/schema and status definitions before preparing a query; do not substitute a generic queue_table placeholder.

A finished local export can still be waiting for a downstream importer. A queue can also be empty because the producer never dispatched work, or because Meduse's configured connection executed it inline. Use the linked workflow to determine what each state proves.

Production process checks, database queries, logs, restarts and replays each require explicit approval for the exact command and target. Reading this runbook does not authorize running them.

Step 3: Identify failed work items

Look for work items 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:

Symptom	Likely cause
All tasks failing	External service unavailable (Magento API, carrier)
Repeated deadlocks	Concurrency on the same records
Slow tasks	Unoptimized query, large data volume
Stuck processor	Zombie process, unreleased lock

Step 5: Resolve and validate

1. Fix the root cause
2. Determine whether the failed operation can safely be retried; inspect partial writes and destination state first
3. Obtain approval for any production recovery action and target
4. Verify the affected item at the destination as well as its local queue/file state
5. For replay planning, see Replay Failed Jobs; do not infer replay safety from a failed status alone

Ongoing monitoring

• Document and supervise the required consumer for each queue; confirm the configured process manager and restart policy with the environment owner
• Set up alerts on task accumulation
• Monitor the relevant consumer error logs