Monitoring and Troubleshooting

Monitoring and troubleshooting

Open System → NetSuite → Monitor Dashboard in Admin. The monitor tracks import and export jobs, payloads, processing messages, and related queue IDs. Access is controlled by the module's NetSuite ACL resource.

Queue and monitor are separate records

The custom queue is mageos_netsuite_message; history is mageos_netsuite_monitor. Queue names are still netsuite_import and netsuite_export. A successful job normally removes its queue row while retaining monitor history, unless Remove successful items is enabled.

Do not use Magento's standard queue_message or queue_message_status tables as the connector's work queue. Do not confuse a monitor ID with a queue message ID.

Status	Meaning
in_queue	Awaiting processing.
in_progress	Claimed for execution.
retry	Rejected for another attempt.
done	Successfully processed according to the processor.
error	Terminal or explicitly forced error.
cancelled	Monitor cancellation label; the Admin Cancel action does not cancel the underlying queue row in this version.

Pending selection includes in-queue and retry messages, ordered by attempts, status, priority, and message ID. The configured retry timeout is not applied to that selection. Default-priority messages reach terminal error after ten trials; nonzero-priority records do not use that same simple limit.

Import batch size is a target rather than a strict cap. The current loop can take an extra 50-record chunk at the default setting of 100. Account for actual processed counts and duration when tuning workers.

Investigate before replaying

1. Record the entity, queue ID, monitor ID, NetSuite ID, failure text, and time. Keep customer data and credentials in restricted incident evidence.
2. Confirm the correct connection and feature flag. A successful Test Connection only proves the server-time request succeeds.
3. Check that required product/customer/order links, custom fields, payment/shipping mappings, and role permissions exist.
4. Inspect the corresponding NetSuite transaction before replaying an export that timed out or had an uncertain response.
5. Correct the underlying mapping or data issue, then replay the specific existing queue message or intentionally reprocess the business record.
6. Verify the business result in both systems and check that inventory, money, notification, and duplicate effects are correct.

Run Again returns an existing queue message to the pending state and resets its attempts. It does not immediately execute synchronization or reconstruct a deleted queue message. The next scheduled worker must run.

Cancel currently changes only the monitor record. It cannot be relied on to stop pending work. Stop the relevant worker schedule through the normal operational process if processing must be halted, then reconcile the actual queue.

The monitor payload editor can persist an overwrite used by later processing. Treat it as a privileged data correction, retain the original, and validate the resulting record. Editing a displayed payload is not a substitute for fixing the source of repeated bad data.

Stuck jobs

The hourly stuck-message job finds in-progress rows older than the configured interval, one hour by default. An initial interrupted attempt can be returned for retry. A later stuck attempt can be marked as error and have its queue row deleted, leaving monitor history behind.

This behavior explains why some error records cannot be restored through Run Again. Reconcile the remote result and original business record before creating new processing work. Do not delete a lock file while a worker is running; flock protects the open file handle.

Logs and health

Default file logs are:

var/log/netsuite_system.log
var/log/netsuite_exception.log

CLI verbosity can route diagnostic messages to command output. Capture scheduled output in a restricted log and rotate it. Debug payloads can contain customer, address, transaction, or payment-related data.

The integration records these last-run flags in Magento's flag storage:

last_import_queue_run_date
last_export_queue_run_date
last_stock_update_date

Monitor queue age and count, last successful business result, last stock refresh, job duration, failure rate, and storage growth. A timestamp or exit code alone is not proof that every record succeeded.

The built-in queue-warning job currently queries Magento's MySQL queue status backend and uses an import identifier for both checks. It does not count this connector's custom queue correctly. Configure independent monitoring until that code is corrected. The inherited Mail errors setting also does not establish a working per-error notification implementation.

Monitor cleanup uses a creation-time cutoff and skips in-queue history. The default lifetime is 30 days. It is history cleanup, not a general queue purge or an audit-retention guarantee.

Import lookback and product pagination

The changed-record search uses the earlier of the saved last-run time and the configured lookback boundary. The default lookback is 15 minutes. This deliberately overlaps recent records, and a prolonged outage can make the next search cover more than 15 minutes. The older documentation's description of a hard maximum is inaccurate for this code.

Product import also persists search pagination under:

var/netsuite/netsuite_import_queue_search_information

It contains search ID and page progress. Inspect that state when investigating a stalled or expired NetSuite search. Do not blindly reset it or the last-run flags: doing so can repeat or skip substantial work.

Common symptoms

Symptom	Check
Orders stay in queue	Separate synchronization schedule, feature flags, worker lock, credentials, monitor error, product links.
Product never appears	SKU mapping, type/eligibility, store/website assignment, import queue delay, batch errors, search pagination.
Stock remains old	Saved-search ID/columns, zero-stock rows, mapping, stock interval, source assignment, last-stock timestamp.
A linked order import fails	Status mapping and the eligibility bypass described in Known limitations.
Location or multi-source fulfillment fails	Known source defects, not merely missing account configuration.
Invoice command rejects a remote invoice	The supported record is CashSale, not NetSuite Invoice.
Error mail stays quiet	Queue-warning implementation mismatch; inspect custom queue and logs directly.
Run Again reports success but nothing runs	Underlying queue row may be gone, or no worker is scheduled.

Sources: Admin menu, message management, queue resource, stuck recovery, Run Again, Cancel, payload save, cleanup, warnings, last-run management, logging.