Skip to main content

Troubleshooting

Solutions to common issues encountered while using GSM Middleware.

Orders Not Syncing​

Symptoms​

  • No new orders appearing in Control Panel
  • order_last_run timestamp not updating
  • Orders showing as "Awaiting Processing" on e-commerce site

Diagnosis​

Check if cron is running:

wp cron event list --path=/path/to/wordpress

Check logs:

tail -f /var/log/gsm-middleware/order-sync.log

Verify site is active:

SELECT name, is_active, orders_sync, order_last_run 
FROM rm_sites 
WHERE id = YOUR_SITE_ID;

Solutions​

Cron Not Running​

# Test cron manually
wp cron test --path=/path/to/wordpress

# Check crontab
crontab -l

# Add if missing
*/5 * * * * cd /path/to/wordpress && php wp-cron.php

Site Disabled​

  1. Go to Control Panel
  2. Find the site
  3. Toggle "Active" switch to ON
  4. Save changes

API Credentials Invalid​

  1. Click "Edit" on site
  2. Update API credentials
  3. Click "Test Connection"
  4. Save if successful

Database Connection Lost​

  1. Go to Settings → DB Environments
  2. Test the active environment
  3. If failed, update credentials
  4. Activate and save

BC Export Failures​

Orders Stuck in "Pending Insert"​

Symptoms:

  • High pending_insert count
  • No decrease over time
  • Errors in rm_order_import_errors

Check error log:

SELECT order_number, message, created_at
FROM rm_order_import_errors
ORDER BY created_at DESC
LIMIT 20;

Common causes:

Invalid Ship-To Code​

Error: Ship-To Code '' does not exist.

Solution:

-- Check the problematic order
SELECT ship_state, ship_to_code 
FROM rm_order 
WHERE number = 'BGM-12345';

-- Update if needed
UPDATE rm_order 
SET ship_to_code = 'WAREHOUSE' 
WHERE number = 'BGM-12345';

Missing Payment Method​

Error: Payment Method Code '' is not valid.

Solution:

-- Update order with correct payment method
UPDATE rm_order 
SET payment_method = 'CREDITCARD' 
WHERE number = 'BGM-12345';

Invalid Bill-To Customer​

Error: Bill-to Customer No. must have a value.

Solution:

-- Set default customer
UPDATE rm_order 
SET bill_to_customer_code = 'WEB00001' 
WHERE number = 'BGM-12345';

Orders Stuck in "Pending Verify"​

Symptoms:

  • Orders inserted but not verified
  • No nav_sales_order_number after 30+ minutes

Check if verify cron is running:

# Check log
tail -f /var/log/gsm-middleware/bc-verify-items.log

# Run manually
php /path/to/wordpress/wp-content/plugins/gsm-middleware/cron/bc-verify-items.php

Possible causes:

  1. BC API Slow/Timeout: Wait longer, verify cron runs every 15 minutes
  2. Order Not Actually in BC: Check BC manually using Web API or Client
  3. Date Filter Too Restrictive: Verify operation looks back 7 days by default

Manual verification:

-- Get external document number
SELECT number, nav_external_doc_number 
FROM rm_order 
WHERE number = 'BGM-12345';

-- Check if already verified
SELECT number, nav_sales_order_number, verified 
FROM rm_order 
WHERE nav_external_doc_number = 'BGM-12345-12345678';

SKU Verification Errors​

"Bad SKU" Errors​

Symptoms:

Order BGM-12345 skipped — bad SKUs: INVALID-SKU-001

Diagnosis:

-- Check if SKU exists in middleware
SELECT prod_id, sku, description, item_status
FROM rm_items
WHERE sku = 'INVALID-SKU-001';

If SKU not found:

  1. Check if it exists in Business Central
  2. Run inventory sync: php cron/inventory-sync.php
  3. Reprocess order from Test Order tool

If SKU has blocked status:

-- Check status
SELECT sku, item_status FROM rm_items WHERE sku = 'INVALID-SKU-001';

-- Check if status is blocked
SELECT gsm_middleware_item_status_not_allowed FROM wp_options;

Solutions:

  1. Add SKU to Business Central if it doesn't exist
  2. Unblock SKU in Business Central if status is blocked
  3. Run inventory sync to update middleware
  4. Reprocess order from Control Panel → Test Order

"SKU Not in Middleware" Warnings​

Symptoms:

Order BGM-12345 — SKUs not yet in middleware; will retry.

This is normal! The order will automatically retry after the next inventory sync.

If persisting for hours:

# Force inventory sync
php /path/to/wordpress/wp-content/plugins/gsm-middleware/cron/inventory-sync.php

Inventory Not Updating​

Symptoms​

  • Inventory quantities not changing on e-commerce sites
  • inventory_last_run not updating
  • Out of stock items still showing as available

Diagnosis​

Check inventory sync status:

SELECT name, inventory_sync, inventory_last_run
FROM rm_sites
WHERE id = YOUR_SITE_ID;

Check for errors:

tail -f /var/log/gsm-middleware/inventory-sync.log

Test manually:

SITE_ID=5 php /path/to/wordpress/wp-content/plugins/gsm-middleware/cron/inventory-sync.php

Solutions​

Site Inventory Sync Disabled​

  1. Go to Control Panel
  2. Edit the site
  3. Enable "Inventory Sync"
  4. Save

API Rate Limiting​

Symptoms:

Error: Too Many Requests (429)

Solution:

  • BigCommerce: Adjust BIGCOMMERCE_API_RATE_LIMIT setting
  • WooCommerce: Increase server limits or batch size

Item Not Found in Business Central​

-- Check if item exists
SELECT sku, navision_sku, item_status
FROM rm_items
WHERE sku = 'PROBLEM-SKU';

If navision_sku is NULL or different:

  1. Update in Business Central
  2. Run inventory sync

Tracking Numbers Not Appearing​

Symptoms​

  • Orders shipped in BC but tracking not on e-commerce site
  • tracking_last_run not updating

Diagnosis​

Check tracking sync status:

SELECT name, tracking_sync, tracking_last_run
FROM rm_sites
WHERE id = YOUR_SITE_ID;

Check if order has BC Sales Order Number:

SELECT number, nav_sales_order_number, verified
FROM rm_order
WHERE number = 'BGM-12345';

Check BC for tracking:

-- Query Business Central (via OData or SQL)
SELECT No_, Package_Tracking_No
FROM Sales_Shipment_Header
WHERE Order_No_ = 'NAV-SO-12345';

Solutions​

Site Tracking Sync Disabled​

  1. Enable in site configuration
  2. Run tracking sync manually

Order Not Yet Verified​

  • Wait for verify operation to complete
  • Check verified=1 and nav_sales_order_number populated

Tracking Not in BC Yet​

  • Wait for BC to process shipment
  • Check with warehouse/fulfillment team

Run Tracking Sync Manually​

SITE_ID=5 php /path/to/wordpress/wp-content/plugins/gsm-middleware/cron/tracking-sync.php

Database Connection Issues​

"Unable to connect to database" Error​

Check connection details:

SELECT name, environment, db_host, db_name
FROM rm_db_environments
WHERE is_active = 1;

Test connection:

mysql -h HOST -u USER -pPASSWORD DATABASE_NAME

Common causes:

Wrong Credentials​

  1. Go to Settings → DB Environments
  2. Click "Edit" on active environment
  3. Update credentials
  4. Click "Test Connection"
  5. Save if successful

Database Server Down​

# Check if MySQL is running
sudo systemctl status mysql

# Restart if needed
sudo systemctl restart mysql

Firewall Blocking Connection​

# Test connectivity
telnet DB_HOST 3306

# Check firewall rules
sudo iptables -L

Max Connections Reached​

-- Check current connections
SHOW PROCESSLIST;

-- Check max connections
SHOW VARIABLES LIKE 'max_connections';

-- Increase if needed
SET GLOBAL max_connections = 500;

API Connection Failures​

BigCommerce API Errors​

401 Unauthorized​

Error: Unauthorized (401)

Causes:

  • Invalid API credentials
  • Expired access token
  • Wrong store hash

Solution:

  1. Verify credentials in BigCommerce store settings
  2. Regenerate API credentials if needed
  3. Update in GSM Middleware
  4. Test connection

404 Not Found​

Error: Not Found (404)

Causes:

  • Wrong store URL/hash
  • API endpoint changed
  • Store deleted/suspended

Solution:

  1. Verify store hash: https://api.bigcommerce.com/stores/{store_hash}/v3/catalog/products
  2. Update store URL in site settings
  3. Test connection

429 Too Many Requests​

Error: Too Many Requests (429)

Solution:

  1. Wait for rate limit to reset (typically 1-5 minutes)
  2. Reduce sync frequency
  3. Contact BigCommerce to increase rate limits

WooCommerce API Errors​

403 Forbidden​

Error: Forbidden (403)

Causes:

  • Invalid consumer key/secret
  • User lacks permissions
  • REST API disabled

Solution:

  1. Regenerate API keys in WooCommerce → Settings → Advanced → REST API
  2. Ensure user has read_write permissions
  3. Verify REST API is enabled

SSL Certificate Errors​

Error: SSL certificate problem

Solution:

// Temporarily disable SSL verification (NOT for production)
add_filter('https_ssl_verify', '__return_false');

Better solution:

  1. Install valid SSL certificate
  2. Update CA certificates: sudo update-ca-certificates

Business Central OData Errors​

401 Unauthorized​

Check credentials:

  1. Go to Settings → API Connections
  2. Test the active Navision connection
  3. Update username/password if needed

Slow Response Times​

Symptoms:

  • Operations timeout
  • "Execution time exceeded" errors

Solutions:

  1. Reduce batch sizes in settings
  2. Optimize OData queries (add filters)
  3. Contact BC administrator about performance
  4. Consider scheduling during off-peak hours

Maintenance Window​

Message:

Skipping sync - GSM maintenance window (Sunday 19:00 - Monday 04:00 UTC)

This is expected! All sync operations automatically pause during this time.

External API Issues​

Debugging with User-Agent Headers​

Since v1.18.45, GSM Middleware includes a standardized User-Agent header in all HTTP requests:

User-Agent: GSM Middleware/1.18.45

Benefits for troubleshooting:

1. Request Identification​

When working with API provider support teams (BigCommerce, WooCommerce, Signifyd, NMI, BazaarVoice), they can filter their logs by User-Agent to identify your requests:

# Example: BigCommerce support can search logs for
User-Agent: GSM Middleware/1.18.45

2. Rate Limiting Diagnosis​

If you're experiencing rate limiting issues, API providers can:

  • Track your request patterns
  • Identify peak usage times
  • Recommend optimization strategies
  • Adjust rate limits for your specific instance

3. Version-Specific Issues​

Support teams can quickly identify which version of GSM Middleware is making requests, helping to:

  • Diagnose version-specific bugs
  • Recommend upgrades if issues are fixed in newer versions
  • Track API compatibility changes

4. Request Tracking Examples​

BigCommerce API Logs:

2026-05-27 10:30:15 - GET /stores/abc123/v3/catalog/products
User-Agent: GSM Middleware/1.18.45
Status: 200 OK
Response Time: 142ms

WooCommerce API Logs:

[2026-05-27 14:22:03] INFO: REST API request
Endpoint: /wp-json/wc/v3/orders
User-Agent: GSM Middleware/1.18.45
Authentication: Successful

Signifyd API Logs:

POST /v3/orders/events/chargebacks
User-Agent: GSM Middleware/1.18.45
Request-ID: req_abc123xyz
Status: 201 Created

Working with API Provider Support​

When contacting support about API issues, provide:

  1. Your Version: "GSM Middleware v1.18.45"
  2. Timestamp: When the issue occurred (with timezone)
  3. User-Agent String: GSM Middleware/1.18.45
  4. Request Details: Endpoint, method, parameters
  5. Error Response: Status code and error message

Example support request:

Hi BigCommerce Support,

We're experiencing 429 rate limiting errors from our middleware integration.

  • User-Agent: GSM Middleware/1.18.45
  • Store Hash: abc123
  • Timeframe: May 27, 2026, 10:00-11:00 UTC
  • Endpoint: /stores/abc123/v3/catalog/products
  • Request Pattern: Hourly inventory sync (approx. 5,000 products)

Can you help us identify if we're exceeding rate limits and suggest optimization strategies?

Common API Provider Responses​

BigCommerce​

  • "We see your requests from User-Agent GSM Middleware/1.18.45"
  • "Your rate limit is 450 requests per 30 seconds"
  • "We recommend spreading requests across the hour"

WooCommerce​

  • "REST API logs show successful authentication from GSM Middleware"
  • "Consider using webhooks instead of polling for order updates"
  • "Enable WooCommerce Action Scheduler for better performance"

Signifyd​

  • "Requests from your User-Agent are processing correctly"
  • "Case submission latency is 200ms average"
  • "Consider batching case submissions if needed"

Performance Issues​

Slow Admin Interface​

Solutions:

  1. Clear browser cache
  2. Disable browser extensions
  3. Check for JavaScript errors in console
  4. Reduce number of sites (archive inactive ones)

Slow Sync Operations​

Check execution times:

grep "Total execution time" /var/log/gsm-middleware/*.log

Optimize:

  1. Increase PHP memory limit: memory_limit = 512M
  2. Increase PHP max execution time: max_execution_time = 300
  3. Add database indexes on commonly queried columns
  4. Archive old orders (>90 days)

High Database Load​

Check slow queries:

-- Enable slow query log
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;

-- Review slow queries
SELECT * FROM mysql.slow_log;

Optimize:

  1. Add indexes to rm_order, rm_lineitems, rm_items
  2. Archive old data
  3. Increase database server resources
  4. Consider read replicas for reporting

Getting More Help​

Enable Debug Logging​

WordPress:

// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Plugin:

// Increase log verbosity (if available)
define('GSM_MIDDLEWARE_DEBUG', true);

Collect Diagnostic Info​

When reporting issues, include:

  1. PHP Version: php -v
  2. WordPress Version: wp core version
  3. Plugin Version: Check plugin headers
  4. Error Messages: From logs and database
  5. Steps to Reproduce: Detailed steps
  6. Expected vs Actual: What should happen vs what does happen

Useful Commands​

# Check WordPress cron
wp cron event list

# Check PHP errors
tail -f /var/log/php-fpm/error.log

# Check database connectivity
wp db check

# Check file permissions
ls -la /path/to/wordpress/wp-content/plugins/gsm-middleware

Next Steps​