NetSuite Custom Tool Error Messages: Troubleshooting by Stage

NetSuite custom tool error messages identify the stage that failed: File Cabinet access, module loading, parameter validation, execution-context preparation, session authorization, runtime execution, or result return. Preserve the exact message first, then investigate the condition associated with that stage.

TL;DR: Review the enclosing File Cabinet folder for Access denied., remove N/http, N/https, and N/sftp for the unsupported-module message, provide the required properties named in a parameter error, and keep preparation, permission, runtime, and result-return failures separate.

Key takeaways

Access denied. concerns the File Cabinet folder containing the custom tool, not an individual file restriction.
Existing subfolders do not automatically inherit a restriction added to a parent folder later.
Custom tool scripts cannot load N/http, N/https, or N/sftp.
Preparation, session authorization, runtime execution, and result return are separate failure stages.
There was an unexpected error while executing the tool: <error details> is an execution failure; Tool execution failed means the tool did not return a result properly.

Use the exact message to identify the failed stage

Each message shows how far NetSuite progressed. An access error concerns the File Cabinet folder; a module-loading error occurs before the tool can proceed; and a result-return error means the tool did not return a result properly. Start with the complete text rather than treating every message as a script exception.

Error message	Failed stage	First supported check
`Access denied.`	File Cabinet access	Review restrictions on the enclosing folder for the current role.
`Couldn't load modules in the custom tool script because it uses unsupported modules. Remove the unsupported modules from the script.`	Module loading	Remove `N/http`, `N/https`, and `N/sftp` if used.
`Invalid call, the following required properties are missing: [parameter1, parameter2]`	Parameter validation	Provide the properties named in the message.
`The script execution context creation failed due to the following issue: <error details>`	Execution preparation	Review the critical preparation issue in `<error details>`.
`This tool is not allowed`	Session authorization	Check the permission required by the tool in the current session.
`There was an unexpected error while executing the tool: <error details>`	Runtime execution	Use the details to investigate the failing line or exception.
`Tool execution failed`	Result return	Review whether the tool returns a result properly.

This stage map prevents wasted investigation. Do not start with result-return behavior when the folder is inaccessible, and do not treat a context-creation failure as a runtime exception. For more examples, see common NetSuite developer tool errors.

1. `Access denied.`: review File Cabinet folder restrictions

Meaning: The user's role does not have access to the File Cabinet folder containing the custom tool. File access restrictions apply to folders, not individual files.

Supported next step: Review the enclosing folder's restricted-access settings:

Log in with a role that has access to the folder.
Go to Documents > Files > File Cabinet.
Click Edit for the folder.
Select restrictions from the available lists for class, department, location, or group.

List names can differ when record naming has been customized in the account. Review the names displayed in the account rather than assuming the labels are identical everywhere.

Folder restrictions can use criteria such as location and department. A private folder is available only to its creator and the account administrator. Administrators can view every folder, including private and restricted folders, and a folder owner has access regardless of restrictions. A successful administrator test therefore does not establish that the affected role can access the folder.

For related File Cabinet context, see Credentials File Management in NetSuite 2026.1.

Check parent and subfolder timing

If a subfolder is created after its parent has been restricted to a group, the subfolder automatically inherits that parent restriction. The restriction can later be changed on the subfolder.

The reverse does not happen automatically. If a parent folder is restricted after a subfolder already exists, that subfolder does not inherit the new parent restriction. Apply the restriction to the existing subfolder manually when needed.

Dynamic groups add another timing consideration. NetSuite restricts a folder to a snapshot of the selected dynamic group's members for performance reasons, and that snapshot is updated twice daily. When access changes unexpectedly, establish whether the subfolder inherited a restriction, has a manual restriction, or relies on a dynamic-group snapshot.

2. Unsupported-module error: remove `N/http`, `N/https`, and `N/sftp`

Message: Couldn't load modules in the custom tool script because it uses unsupported modules. Remove the unsupported modules from the script.

Meaning: The custom tool script uses one or more unsupported SuiteScript modules. Custom tool scripts cannot load:

N/http
N/https
N/sftp

Supported next step: Remove the unsupported modules from the script, then run the tool again. This is a loading issue, not a runtime exception: the tool cannot proceed while one or more of these modules are present.

Keep the distinction clear when triaging the issue. Runtime error handling does not address a module-loading message because the loading stage has failed first. For related development reading, see N/error Module Members for SuiteScript 2.1 Development, SuiteScript modular design practices, and SuiteScript 2.x scripting resources.

3. Missing required properties: provide the listed parameters

Message: Invalid call, the following required properties are missing: [parameter1, parameter2]

Meaning: Required parameters are missing. The names in the brackets identify the missing inputs; the example shows that more than one property can be reported.

Supported next step: Provide every property listed in the message. Preserve the exact property names and compare them with the properties supplied by the failing invocation. This message identifies a parameter problem; it does not indicate that execution reached a failing script line.

After supplying the listed properties, repeat the same call. If NetSuite displays a different message, use that new message to identify the next failed stage.

4. Execution-context creation failed: inspect preparation details

Message: The script execution context creation failed due to the following issue: <error details>

Meaning: A critical error occurred during execution-context preparation, so the tool could not run. The message includes <error details> for the preparation issue.

Supported next step: Capture and inspect the complete details before changing runtime logic. This message distinguishes a preparation problem from an error that occurred while executing a line of the tool. Resolve the critical preparation condition, rerun the same tool, and classify any subsequent message separately.

5. `This tool is not allowed`: check the current session permission

Meaning: The tool requires a permission that the current session does not have. This differs from Access denied., which specifically identifies access to the File Cabinet folder containing the tool.

Supported next step: Identify the permission required by the tool and compare it with the permissions available to the user in the current session. Test using the intended operational role rather than relying only on an administrator or a broader development role.

Do not treat this as a folder-restriction or unsupported-module message. NetSuite has identified session authorization as the failed stage. For related account setup context, see how SuiteScript features and roles are enabled.

6. Unexpected execution error: use the error details

Message: There was an unexpected error while executing the tool: <error details>

Meaning: The tool reached execution but failed on a line or threw an exception. The message includes error details.

Supported next step: Preserve the complete <error details> text and use it to investigate the failing line or exception. Keep the same input and role in view when reproducing the issue so the investigation remains tied to the failing execution path.

This is different from module loading, parameter validation, context creation, and session authorization. If diagnostic information is available for the script, use the established Script Execution Logs management workflow to review the failure. Developers can also review enhanced execution logs for custom tool scripts.

The NetSuite script time limits and debugger rules are separate reference material. This custom tool message itself establishes only that execution failed on a line or threw an exception; the included details are the primary evidence.

7. `Tool execution failed`: review result return behavior

Meaning: The custom tool did not return a result properly. This is a result-return problem rather than the runtime-exception message that identifies a failed line or thrown exception.

Supported next step: Review the tool's result-return behavior and rerun the exact scenario that produced the message. Focus on what the tool returns rather than beginning with File Cabinet access or unsupported modules.

The important distinction is the exact message:

There was an unexpected error while executing the tool: <error details> means execution failed on a line or threw an exception and provides details.
Tool execution failed means the tool did not return a result properly.

If the same tool displays different messages under different inputs, troubleshoot each occurrence according to its own stage.

FAQ

What does `Access denied.` mean when I open a custom tool?

It means the current user's role cannot access the File Cabinet folder containing the custom tool. Restrictions apply to folders, not individual files. Review the enclosing folder at Documents > Files > File Cabinet.

Should I check the file or folder for custom tool access restrictions?

Check the folder. Log in with a role that can access it, go to Documents > Files > File Cabinet, click Edit for the folder, and review restrictions for class, department, location, or group.

Which SuiteScript modules prevent a custom tool from loading?

Custom tool scripts cannot load N/http, N/https, or N/sftp. Remove the unsupported modules before retrying the tool.

Do existing subfolders inherit a parent restriction added later?

No. A subfolder created after its parent is restricted to a group inherits that restriction, but an existing subfolder does not automatically inherit a restriction added to the parent later. Apply the restriction manually where needed.

What is the difference between an unexpected execution error and `Tool execution failed`?

There was an unexpected error while executing the tool: <error details> means execution reached a line that failed or threw an exception. Tool execution failed means the tool did not return a result properly.