Common Issues

Connection Issues

Connection fails right after entering credentials

This usually means one of the five credential fields (Realm, Consumer Key, Consumer Secret, Token Key, Token Secret) is incorrect, or Token-Based Authentication / REST Web Services aren't enabled on the account.

Fix:

1. Confirm Token-Based Authentication and REST Web Services are enabled under Setup → Company → Enable Features → SuiteCloud.
2. Confirm the Integration record has Token-Based Authentication turned on, and the Access Token is active and assigned to the correct role.
3. Re-check the Realm value — see the next issue for the correct format.

Realm (Account ID) format is rejected or connects to the wrong environment

The Realm must match your NetSuite account ID exactly. Production accounts use the numeric ID alone (e.g., 1234567); sandbox accounts append a suffix (e.g., 1234567_SB1). Entering a hostname or URL instead of the account ID will fail.

Fix: Use just the account ID, with the sandbox suffix if applicable. You can find it under Setup → Company → Company Information, or in the domain of your NetSuite URL.

Lost the Consumer Secret or Token Secret

NetSuite only displays the Consumer Secret and Token Secret once, when they're generated. If you didn't save them, there's no way to retrieve them afterward.

Fix: Create a new Access Token (Setup → Users/Roles → Access Tokens → New) and reconnect the source in Coupler.io with the new Token Key and Token Secret.

Permission Errors

403 error or "insufficient permission" for a specific object

The role assigned to your Access Token doesn't have permission to view that record type in NetSuite.

Fix: In NetSuite, edit the role used for the Access Token (Setup → Users/Roles → Manage Roles) and grant view permission for the record type, or create a token under a role that already has broader access.

Error reading an Admin-only record

Some record types are restricted to the Administrator role in NetSuite. If the Access Token's role isn't Administrator, requests for these records fail.

Fix: Use an Access Token created under the Administrator role for objects that require it, or skip that object if broader access isn't appropriate for your integration.

SuiteQL Issues

SuiteQL query returns "Invalid search query" error

NetSuite rejected the query — usually due to a syntax error, an unknown table/column name, or a reference to a field that doesn't exist on that record.

Fix: Check the exact error detail returned (Coupler.io surfaces NetSuite's own message), and confirm table and field names against NetSuite's SuiteQL documentation. Test the query in NetSuite's SuiteQL query tool if you're unsure it's valid.

SuiteQL query fails because it exceeds 100,000 rows

NetSuite's REST API caps SuiteQL results at 100,000 rows per query. Queries that would return more fail instead of returning a partial result.

Fix: Narrow the query with a tighter WHERE clause (e.g., a date range), or aggregate/summarize in the query itself rather than pulling raw rows. There's no way to paginate past this limit through the REST API.

Data Gaps

Start date doesn't seem to filter a particular object

The Start date and Window in days parameters only apply to record types that expose a last-modified field (lastModifiedDate or lastmodified). Record types without one of these fields don't support incremental filtering and are synced in full on every run.

Fix: This is expected for those record types — there's no incremental option available for them via the Objects data type. Use SuiteQL with a date filter in the WHERE clause if you need to scope the export.

An object returns no data or fewer records than expected

If the object type doesn't exist or isn't accessible in your account, NetSuite returns an error that Coupler.io logs without failing the entire data flow — so the object silently returns no rows instead of an obvious error.

Fix: Verify the object name against the ones available in your account's metadata catalog (shown in the Object dropdown when creating the data flow), and confirm the token's role has access to it.