cloudflare-queues:troubleshoot

Queue Troubleshoot Command

Troubleshoot Cloudflare Queue issues with systematic checks.

Usage: /queue-troubleshoot my-queue-name

Step 1: Validate Input

If queue name provided as argument ($1), use it. If not provided, ask user:

• "Which queue name do you want to troubleshoot?"
• Store as: queueName

Step 2: Quick Status Check

Run diagnostics in parallel:

# Check if queue exists
wrangler queues list

# Get queue details
wrangler queues info $queueName

Analyze output for:

• ✅ Queue exists and is listed
• ⚠️ High backlog (>100 messages)
• ⚠️ No active consumer
• ❌ Queue not found (doesn't exist)

Output Example:

Queue Status: my-queue
├── Exists: ✅ Yes
├── Backlog: ⚠️ 250 messages (high)
├── Consumers: ⚠️ 0 active (no consumer configured)
└── Last Activity: 5 minutes ago

Step 3: Configuration Check

Read wrangler.jsonc/wrangler.toml and verify:

Producer Check:

• Search for queues.producers array
• Check if any binding references $queueName
• Verify binding name is valid JavaScript identifier

Consumer Check:

• Search for queues.consumers array
• Check if any consumer references $queueName
• Verify settings are reasonable:
  • max_batch_size: 1-100
  • max_retries: 1-10 (3 is typical)
  • max_concurrency: 1-20 (1-5 is typical)
• Check if dead_letter_queue configured

Output Example:

Configuration Check:
Producer:
  ✅ Binding: MY_QUEUE → my-queue

Consumer:
  ❌ NOT CONFIGURED
  → Recommendation: Add consumer configuration:
    ```jsonc
    {
      "queues": {
        "consumers": [{
          "queue": "my-queue",
          "max_batch_size": 10,
          "max_retries": 3
        }]
      }
    }
    ```

DLQ:
  ⚠️ Not configured (recommended for production)

Step 4: Common Issues Check

For each common issue, check and provide fix:

Issue 1: Messages Not Being Consumed

Symptom: Backlog growing, no consumer errors Check:

• Is consumer configured in wrangler.jsonc?
• Is Worker deployed with queue handler?
• Is queue() export present in Worker?