> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/sales/netsuite/common-issues.md).
# 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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.coupler.io/sources/category/sales/netsuite/common-issues.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.