2.6 Troubleshooting

Order Daemon is designed for reliability, but in a complex environment like WordPress and WooCommerce, issues can still arise. This guide will walk you through the most common troubleshooting steps.

The Golden Rule: Start with the Insight Dashboard

The Insight Dashboard is your most powerful troubleshooting tool. Before trying anything else, find the relevant order or timeframe in the log stream and examine the entries. The answer is almost always there.

1. Navigate to WooCommerce → Insight Dashboard.
2. Use the search filter to find log entries for the specific Order ID you are investigating (e.g., search for “1234”).
3. Carefully read the Summary for each event in the log stream.
4. Click any log entry to view detailed information in the expandable details pane.
5. Use the Include Debug Logs checkbox if you need more detailed execution information. Note that Order Daemon only records debug logs if ODCM_DEBUG is set to true.

Common Scenarios

Here are some common problems and how to diagnose them using the Insight Dashboard.

Scenario: An order was not automatically completed.

If an order you expected to be completed is still in a “Processing” state, the log stream will tell you why.

1. Look for aNoticeentry: You will often see a message like: No matching completion rules found for order #[Order ID].
   • Meaning: The daemon processed the order, but its products, total value, or other attributes did not match the conditions of any of your active rules.
   • Solution: Review your Completion Rules. Ensure they are configured correctly to match the order in question and that the rules themselves are active.
2. Look for aWarningentry: The log might indicate a deliberate reason for skipping the order.
   • Meaning: A filter, such as one checking for product conflicts (e.g., physical and virtual items in the same cart), may have instructed the daemon to skip the order. The odcm_order_has_conflicts filter is a common source for this.
   • Solution: This is usually expected behavior. If you believe the order should have been processed, you may need to consult a developer to understand what custom logic is attached to the daemon’s filters.
3. If there are no entries for the order at all:
   • Meaning: The Order Daemon was never triggered for that order. This almost always means that the initial event (e.g., payment_complete) never fired.
   • Solution: This points to an issue outside the Order Daemon itself. Check the configuration of your payment gateway. Some gateways have settings that prevent them from automatically triggering the standard WooCommerce hooks that the daemon listens for.

Scenario: An order was completed, but it shouldn’t have been.

1. Find the Success entry: Locate the log entry with the summary: Order #[Order ID] was successfully marked as completed.
2. View the Details: Click the entry to expand the details pane.
   • Meaning: The Rule ID field will tell you exactly which rule was responsible for completing the order.
   • Solution: Go to WooCommerce → Order Daemon → Completion Rules and edit the identified rule. Its conditions are likely too broad. For example, a rule intended only for virtual products might be missing a condition to check the product type. Adjust the rule’s conditions to be more specific. Also, check the rule’s priority, as it may be running before a more specific rule.

Scenario: The Insight Dashboard is blank or appears broken.

1. Meaning: This typically indicates a JavaScript or CSS conflict with another plugin or your theme, which is preventing the dashboard from rendering correctly.
2. Solution:
   • Open your browser’s developer tools and check the Console for any JavaScript errors.
   • Perform a conflict check by temporarily deactivating other plugins (especially any that heavily modify the admin interface) and switching to a default WordPress theme (like Twenty Twenty-Four) to see if the issue resolves.
   • Check if Alpine.js is loading correctly.

Scenario: Debug information is not appearing.

1. Enable Debug Mode: Go to WooCommerce → Insight Dashboard, click the gear icon, expand Debug Settings, and check “Enable Global Debug Mode”.
2. Check the Include Debug Logs filter: Make sure the “Include Debug Logs” checkbox is checked in the filter pane.
3. Verify ODCM_DEBUG: Debug logs only appear when ODCM_DEBUG is set to true either via the dashboard or in wp-config.php.

Understanding Order Processing Timing

Many troubleshooting cases are timing-related. Order Daemon follows WooCommerce’s lifecycle and defers heavy work to the background, which means a short delay between the store event and automation execution is expected.

Lifecycle Recap and Hook Mapping

• Order Creation → schedules async evaluation via woocommerce_checkout_order_processed (internal; non-selectable)
• Payment Complete → primary trigger woocommerce_payment_complete
• Status Transitions → optional triggers woocommerce_order_status_on-hold, woocommerce_order_status_processing
• Refunds → woocommerce_order_fully_refunded and related hooks for cleanup/diagnostics

Asynchronous Pipeline (What actually happens)

1. Event fires (e.g., payment complete)
2. Order Daemon enqueues a background job (odcm_process_order_check)
3. Action Scheduler picks up the job and runs rule evaluation
4. On success/failure, results are logged to the Insight Dashboard, and retries occur automatically on transient failures

Typical Timing Patterns

• Instant payments (credit cards): Completion checks usually run within seconds of payment_complete
• Delayed gateways (bank transfer, check): Orders may go to On Hold first; completion occurs after you move to Processing or after verification
• PayPal/eWallets: Gateway confirmations can be delayed; processing may happen minutes later depending on provider and site traffic
• High traffic: A larger Action Scheduler queue can add delay; checks still run reliably as capacity frees up
• Block Checkout: Observed at checkout; completion still runs in the same async pipeline afterward

Diagnosing Timing Issues

• Check Tools → Scheduled Actions for pending odcm_process_order_check jobs; run any that are stuck
• Ensure WP Cron or an external cron runner is active so Action Scheduler can process the queue
• Confirm your gateway actually fires payment_complete (some “authorize only” configurations do not)
• If multiple events fire (e.g., payment complete and status change), deduplication may skip one enqueue — this is expected and prevents duplicates
• Compare event timestamps in the Insight Dashboard to understand sequencing

For choosing the best trigger per gateway, see Understanding Triggers. For a deeper architectural view, see Technical Overview → WooCommerce Integration Deep Dive.

When to Contact Support

If you have thoroughly checked the Insight Dashboard and are still unable to resolve the issue, please be prepared to provide our support team with the following information:

• A detailed description of the problem.
• The specific Order ID(s) involved.
• A screenshot of the relevant log entries from the Insight Dashboard, with the details pane expanded.
• Your current versions of WordPress and WooCommerce.
• Whether debug mode was enabled during the issue (ODCM_DEBUG setting).

For more information, check out our support page.