Troubleshooting

Start with the doctor

/su-ns-harness:doctor

It checks Node, the write mode, which connector keys the cache, cache freshness, disk usage, when each hook last fired, logged hook errors, and whether the connector answers. To test the connector it makes one read-only ns_getSubsidiaries call, and it changes nothing in NetSuite. You get a ✓/✗ checklist with one fix per ✗.

Claude also runs it on its own when NetSuite results come back raw with no [su-ns-harness] line.

Why do NetSuite results come back raw, with no [su-ns-harness] line?

The hooks aren't running in this session. The most common cause is installing or updating the plugin mid-session, which can leave it loaded late or only partly. The skills may show up while the hooks still don't fire.

Run /reload-plugins, or start a new session. Don't rely on any of the plugin's checks until you have.

If you didn't just install it, check /hooks and /plugin to see that su-ns-harness is enabled.

Why do tool hooks fire but SessionStart doesn't?

The cause is the same: the plugin was installed mid-session. So is the fix, /reload-plugins or a new session. The account profile arrives with the next session start.

Why does nsx say another data dir exists?

Claude Code in the desktop app and the Claude Code CLI can give the plugin different data directories, for example su-ns-harness-inline and su-ns-harness-suiteutils. Each one keeps its own cache, so each runs its own init.

nsx uses the data directory Claude Code gives its own install, named <plugin>-<marketplace>, for example su-ns-harness-suiteutils. It does that even before the first NetSuite call has created the directory. Other installs' directories are ignored, and nsx names them once per session in one stderr line:

nsx: using su-ns-harness-suiteutils (this install's data dir, hooks last fired 1m ago); su-ns-harness-inline is another install's cache and is ignored. Set NSX_DATA_DIR to pick another.

That line is information, not an error. nsx doctor names both directories. To share one cache, set the NSX_DATA_DIR environment variable to the same directory in every app.

Why does one account have two caches?

The cache is keyed by connector. The claude.ai connector and a Claude Code MCP server are two connectors, even when they reach the same account. To share one cache, set both keys:

nsx config set account_id=1234567 environment=production

If the doctor reports that the cached subsidiaries don't match the connected account, account_id or environment is wrong. A sandbox id saved as production is the usual case. Clear account_id so the cache follows the connector again:

nsx config set account_id=

Why is a query denied because a table isn't in the record-type list?

The connector role can't see that table. NetSuite leaves such tables out of the record-type list it returns, and the plugin denies a query on one before the call, because it would fail with "Record '<table>' was not found". Init skips these tables instead of retrying them.

With no access to subsidiary, init infers the base currency from transactions at exchange rate 1 and marks it for you to confirm.

After widening the role's permissions in NetSuite, refresh the list:

/su-ns-harness:refresh recordtypes

/su-ns-harness:refresh all works too.

Is "no field metadata" for a table a problem?

The connector exposes no field metadata for 'transaction' is normal on many accounts. The table still works in SuiteQL, and the plugin skips its column checks. Only a table missing from the record-type list means the role can't query it.

What does "An unexpected SuiteScript error has occurred" mean?

NetSuite gives this error for a bad column without naming the column. If the checker warned about an unknown column on that query, the plugin reports the error as bad_field_likely and names that column. Otherwise check each column with nsx fields <table> --grep <term> and run the query through nsx sql lint.

Why do calls keep hitting a rate limit?

The account's integration concurrency is shared with every other integration on it, so the connector can rate-limit calls even when Claude sends them one at a time. It shows up as a tool error saying the server is rate-limiting requests, or as HTTP 429 with Concurrent request limit exceeded.

The failure hook tells Claude to wait and retry that one call, one call at a time. The waits are 5, 10 and 20 seconds, each plus up to 3 seconds of jitter. If the third retry is rate-limited too, Claude stops and tells you the account's concurrency is saturated. The count resets once the call succeeds, or after 5 minutes with no rate limit.

This is also why init makes its calls one at a time with pauses, and can take 10 to 15 minutes on a busy account.

SSS_USAGE_LIMIT_EXCEEDED is different. It's NetSuite's governance limit, meaning the call did too much work. Claude narrows the query instead of repeating it.

What do I do when Claude says to reconnect via /mcp?

That's an auth error, or "couldn't reach the MCP server". Claude stops instead of retrying. Re-authenticate:

• Claude Code MCP server: run /mcp, pick the NetSuite server, and choose Authenticate.
• claude.ai connector: reconnect it under Settings → Connectors.

Why don't any NetSuite tools show up?

The connector isn't connected, or it's connected but disabled for this session. In the desktop app's Code tab, open the composer's + menu → Connectors and enable NetSuite. See Installation for both connection routes. For problems with the connector itself, such as roles, permissions or which clients are supported, see Oracle's NetSuite AI Connector Service FAQ.

Why does the plugin do nothing in Cowork or claude.ai?

The plugin installs there, but plugin hooks don't run there. You get the netsuite skill's guidance and nothing else. There's no caching, no result shaping, no SuiteQL checks and no write protection.

The read_only setting isn't enforced, and creates and updates skip the preview and approval step. Control writes through the connector role's permissions instead. Use Claude Code for the full plugin.