Is the error you're chasing the cause, or just a symptom?
The cheapest experiment in debugging: remove the thing you suspect, and see whether the failure notices.
An e-commerce connector was failing to create orders in NetSuite. Not all of them — a handful, all with international addresses. The execution log had exactly one error on those orders, thrown by a payment user event script.
That looked like the answer. A payment script, throwing on the failing orders, absent from the successful ones.
The test that costs five minutes
Instead of reading the payment script, we undeployed it and reran a failing order.
It failed exactly the same way.
That single result eliminated the leading theory and, more importantly, reframed the whole investigation. The payment script wasn't causing the failure — it was downstream of it. Something earlier in the sequence was already broken, and the payment script was simply the first piece of code to trip over the wreckage and say so out loud.
Why the loudest error is so often the wrong one
Error logs are ordered by when something reported a problem, not by when the problem started. A failure early in a chain frequently produces no log entry at all — a record simply doesn't get created — while the next component downstream throws a loud, specific, well-formatted exception.
So the log shows you the first component that was instrumented well enough to complain. That is not the same thing as the first component that broke, and in integration work the two are almost never the same.
In this case the customer record was never created. Nothing logged that, because the failure happened on the connector's side of the API boundary. NetSuite had nothing to report because NetSuite was never asked to do anything.
When the other system holds the evidence
Once you know the failure is upstream, you have to go and look where the logs actually are — which, for any middleware or connector, means the vendor's own dashboard rather than yours.
Two questions worth asking early, because they change the shape of everything:
- Does the integration create related records in one call or several? If customer and order are created in a single transaction, an error anywhere in it rolls back the whole thing — and the error you can see may be from the last step rather than the first.
- Does the vendor's log distinguish "customer creation failed" from "order failed"? Many don't, which is itself a finding: it tells you their error handling collapses distinct failures into one message, and you'll need to reproduce more precisely.
Compare the failures, not the failure
One broken record tells you very little. Three tell you a great deal, because the differences between them are where the cause lives.
Line the failing records up field by field against a working one. In this case the pattern only appeared on the third comparison: the address line was being truncated mid-string, and the state or province value present on the order was missing from the customer record. Both are address-shape problems specific to non-US formats — and neither is visible if you only ever look at one example.
Note also what the comparison ruled out. It wasn't "all international orders" — plenty succeeded. That mattered, because "all non-US fails" and "some non-US fails" point at completely different causes. The first suggests a configuration gap; the second suggests a data-shape edge case, which is what it turned out to be.
The working order
- Name the suspect, then try to eliminate it rather than confirm it.
- Ask what didn't get created, not just what threw. Absent records rarely log.
- Find out which system holds the authoritative log for the failing step.
- Gather at least three failures and diff them against a success.
- Check whether the failure is total or partial — "some" and "all" have different causes.
Related: reading a NetSuite stack trace when the error message is generic.