Troubleshooting Guide

This comprehensive guide helps you diagnose and resolve common issues with the Woo-NetSuite integration. Follow the troubleshooting steps below to identify and fix problems quickly.

General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:

1. Check Plugin Status: Ensure plugin is activated and enabled
2. Verify Credentials: Test NetSuite API connection
3. Enable Debug Logging: Turn on detailed logging for better diagnostics
4. Review Error Logs: Check WordPress and plugin logs for errors
5. Check Queue Status: View queue dashboard for failed jobs
6. Test Connection: Use Test Connection button in settings
7. Update Plugin: Ensure you’re running the latest version
8. Check Server Resources: Verify adequate memory and execution time

Common Issues & Solutions

1. Connection Issues

Issue: Cannot connect to NetSuite API

Error Messages:

• “Connection failed: Authentication error”
• “Invalid login credentials”
• “Could not connect to NetSuite”
• “SSL certificate problem”

Possible Causes & Solutions:

Cause	Solution
Incorrect credentials	Verify all 5 credentials (Account ID, Consumer Key, Consumer Secret, Token ID, Token Secret) in Settings
Account ID format wrong	Ensure Account ID uses underscores (1234567_SB1) not hyphens. Check Company Information in NetSuite
Token expired or revoked	Generate new Access Token in NetSuite, update Token ID and Token Secret in plugin settings
Integration disabled	Verify Integration Record is “Enabled” in NetSuite
Role lacks permissions	Check role assigned to Access Token has required permissions
SSL certificate issue	Ensure your WordPress site has valid SSL certificate, contact hosting provider
Firewall blocking	Whitelist NetSuite IPs in server firewall, contact hosting provider

2. Order Sync Issues

Issue: Orders not syncing to NetSuite

Error Messages:

• “Order sync failed”
• “Customer not found”
• “Product/Item not found”
• “Required field missing”

Troubleshooting Steps:

Check	What to Look For	How to Fix
Order Sync Enabled	Settings > Order Sync > Enable Order Sync = Yes	Enable order sync in settings
Order Status	Check if order status is in “Statuses to Sync” list	Add order status to sync list in settings
Customer Exists	Verify customer exists in NetSuite or will be created	Sync customer first or enable auto-create
Product SKUs	Check all products have SKUs matching NetSuite items	Add/correct SKUs in WooCommerce and NetSuite
Required Fields	Ensure subsidiary, location set in settings	Configure required NetSuite fields in settings
Queue Jobs	Check Queue dashboard for failed order sync jobs	View error details, retry after fixing issue
Order Meta	Look for _netsuite_sync_error in order meta	View error message for specific issue

3. Customer Sync Issues

Issue: Customers not syncing or duplicates created

Common Problems & Fixes:

Problem	Cause	Solution
Duplicate customers	Email matching disabled	Enable “Match by Email” in Customer Sync settings
Missing email error	Guest order without email	Ensure email field required at checkout
Customer not found	NetSuite ID stored but customer deleted	Delete _netsuite_customer_id meta from user, re-sync
Address format error	Invalid international address	Enable address validation, verify country codes
Required field missing	NetSuite requires field not in WooCommerce	Add required field to WooCommerce, use field mapping

4. Inventory Sync Issues

Issue: Inventory not updating from NetSuite

Troubleshooting:

Symptom	Check	Fix
All products show zero stock	Wrong location selected	Verify location configuration in Inventory Sync settings
Specific products not updating	SKU mismatch	Ensure SKU in WooCommerce exactly matches NetSuite Item Number
Stock quantity incorrect	Wrong calculation method	Review Stock Calculation setting (use “Available” recommended)
Variations not syncing	Missing variation SKUs	Add unique SKUs to each product variation
Inventory sync not running	Cron not working	Check WP-Cron status, consider switching to real cron
Inventory sync too slow	Too many products	Increase batch size, reduce sync frequency

5. Fulfillment Sync Issues

Issue: Tracking numbers not appearing

Diagnosis:

Issue	Likely Cause	Solution
No tracking info at all	Fulfillment sync disabled	Enable in Settings > Fulfillment
Tracking missing for one order	Order not linked to Sales Order	Verify order has _netsuite_sales_order_id meta
Tracking in NetSuite but not WooCommerce	Fulfillment not synced yet	Wait for next sync cycle or manually trigger
Wrong carrier name	Carrier mapping mismatch	Configure carrier mapping in settings
Email not sent	Email setting disabled	Enable “Send Customer Email” in Fulfillment settings

6. Queue Problems

Issue: Queue not processing or jobs stuck

Solutions:

Symptom	Diagnosis	Fix
Queue not processing at all	WP-Cron not running	Check cron events: wp cron event list | grep woons – Enable real cron if needed
Jobs stuck “Processing”	Job timeout or PHP crash	Go to Queue dashboard, click “Reset Stale Jobs”
Huge queue backlog	Processing too slow	Increase batch size, add concurrent workers
All jobs failing	API credentials or connection issue	Test connection, verify credentials
Specific job type failing	Data or permission issue	View failed job details for error message

Error Messages Reference

API Errors

Error Code	Message	Meaning	Solution
INVALID_LOGIN_CREDENTIALS	Invalid login credentials	Authentication failed	Verify all 5 credentials correct
USER_ERROR	Required field missing	NetSuite requires a field not provided	Add missing field, check required fields in NetSuite
INVALID_KEY_OR_REF	Invalid record reference	Referenced record doesn’t exist	Verify customer/item exists in NetSuite
INSUFFICIENT_PERMISSION	Insufficient permission	Role lacks permission for this action	Grant required permissions to NetSuite role
RATE_LIMIT_EXCEEDED	Too many requests	Hit NetSuite API rate limit	Reduce sync frequency, increase delays
INVALID_SEARCH_FIELD	Invalid search field	Search field doesn’t exist	Update search query, check field names

Plugin Errors

Error Message	Meaning	Solution
Config key missing: account	Account ID not configured	Enter Account ID in Settings > Credentials
NetSuite service not initialized	SDK couldn’t initialize	Check credentials, test connection
Product SKU not found	SKU doesn’t match any NetSuite item	Verify SKU, check matching method in settings
Customer email required	Order missing customer email	Ensure email captured at checkout
Queue job timeout	Job took too long	Increase timeout in Queue settings

Checking Logs

WordPress Error Logs

Location: wp-content/debug.log (if WP_DEBUG_LOG enabled)

Enable in wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

WooCommerce Logs

1. Navigate to WooCommerce > Status > Logs
2. Select log file starting with “woons-” or “fatal-errors”
3. View errors and stack traces

Plugin Debug Logs

Enable in: Settings > General > Enable Debug Logging

Location: wp-content/uploads/wc-logs/woons-YYYY-MM-DD-[hash].log

View via: WooCommerce > Status > Logs or FTP/File Manager

Reading Debug Logs

Look for these key indicators:

• API Request: Shows data sent to NetSuite
• API Response: Shows NetSuite’s response
• Error: Indicates failure with details
• Warning: Non-critical issues
• Info: General processing information

Diagnostic Tools

System Status

1. Navigate to WooCommerce > NetSuite > System Status
2. View diagnostic information:
   • Plugin version
   • PHP version and settings
   • WordPress and WooCommerce versions
   • Server environment
   • NetSuite connection status
   • Queue status
   • Recent sync statistics
3. Click Copy to Clipboard to share with support

Test Connection Tool

1. Go to Settings > Credentials
2. Click Test Connection button
3. Results show:
   • Connection success/failure
   • API endpoint reached
   • Authentication status
   • Basic permission test
   • Response time

Sync Test Tool

1. Navigate to WooCommerce > NetSuite > Tools
2. Select Test Sync
3. Choose test type:
   • Test Order Sync (creates test Sales Order)
   • Test Customer Sync (creates test customer)
   • Test Inventory Sync (fetches sample inventory)
4. Click Run Test
5. View detailed results and any errors

Performance Issues

Slow Sync Performance

Symptoms:

• Queue taking hours to clear
• Site slowdown during sync
• Timeouts during sync

Solutions:

Action	How	Impact
Increase PHP memory	Set memory_limit = 512M in php.ini	Prevents memory errors
Increase execution time	Set max_execution_time = 300 in php.ini	Prevents timeouts
Optimize batch size	Settings > Queue > Batch Size (try 20-50)	Faster processing
Enable caching	Settings > Advanced > Enable Caching	Reduce API calls
Use real cron	Disable WP-Cron, set up system cron	Reliable scheduling
Schedule off-peak	Run bulk syncs during low-traffic hours	Avoid site slowdown

High API Usage

If hitting NetSuite API limits:

• Reduce sync frequency
• Increase batch processing delay
• Enable caching to reduce duplicate calls
• Use selective sync (only sync changed records)
• Contact NetSuite about increasing limits

Data Issues

Mismatched Data

Order totals don’t match:

1. Check tax calculation settings
2. Verify discount/coupon handling
3. Compare shipping costs
4. Review currency conversion

Customer information incorrect:

1. Check field mapping configuration
2. Verify sync direction setting
3. Review last sync date to determine which system was updated
4. Manually correct in source system and re-sync

Inventory discrepancies:

1. Verify calculation method
2. Check location selection
3. Look for timing issues (order placed between syncs)
4. Enable real-time inventory validation

Getting Help

Before Contacting Support

1. Review this troubleshooting guide
2. Enable debug logging
3. Reproduce the issue
4. Collect:
   • Error messages (exact text)
   • Screenshots of issue
   • Relevant log entries
   • System status report
   • Steps to reproduce

Support Channels

• Documentation: Review all documentation sections first
• Support Ticket: Submit via plugin support page
• Email: [email protected] (with system status attached)
• Priority Support: For license holders (faster response)

Information to Provide

When requesting support, include:

• Plugin version
• WordPress and WooCommerce versions
• PHP version
• Description of issue
• Steps to reproduce
• Error messages
• System status report (copy from System Status page)
• Relevant log entries
• Screenshots if applicable

Preventive Maintenance

Regular Maintenance Tasks

Task	Frequency	Purpose
Check queue dashboard	Daily	Identify stuck or failed jobs
Review sync logs	Weekly	Catch recurring errors early
Test connection	Weekly	Verify credentials still valid
Clear old logs	Monthly	Prevent log file bloat
Update plugin	As available	Get bug fixes and improvements
Review failed jobs	Weekly	Fix issues preventing sync
Audit data accuracy	Monthly	Ensure data stays in sync

Health Monitoring

Set up monitoring for:

• Failed Job Alerts: Email when jobs fail
• Queue Backlog Alerts: Notify if queue gets too large
• Sync Success Rate: Track percentage of successful syncs
• API Error Rate: Monitor for increasing API errors
• Processing Time: Watch for performance degradation

Best Practices to Avoid Issues

• Test in Staging: Test configuration changes before production
• Keep SKUs Consistent: Ensure SKUs match exactly
• Document Customizations: Note any custom code or field mappings
• Regular Backups: Backup database before major changes
• Monitor Logs: Check logs regularly, don’t wait for issues
• Stay Updated: Keep plugin, WordPress, WooCommerce updated
• Use Real Cron: More reliable than WP-Cron for production
• Start Small: Test with small data set before bulk operations