Troubleshooting

Common issues and solutions related to tool creation.

The "Create Tool" button is disabled

You have not entered both a name and a description. Both fields are required. Fill in a descriptive name and a clear description of what the tool does, then try again.

The "Run Test" button is disabled

You have unsaved changes. Save your code first by clicking Save, then the test button becomes active.

My tool fails with a build error

The code could not compile or a dependency could not be resolved. Check the error message in the test results for details. Common causes:

  • Syntax errors in your TypeScript code (missing brackets, typos)
  • An npm package that does not exist or has the wrong name
  • An import URL that is unreachable

Fix the code, save, and run the test again.

My tool fails with "network access denied" or cannot reach the API

The domain is not in the tool's network permissions. Open the Permissions tab in the tool editor, go to Network Access, and add the domain your tool is trying to reach (for example, api.example.com). If the API uses subdomains, consider using a wildcard like *.example.com.

My tool fails with an authentication error from the external API

The API key or token is missing or incorrect. Check the Environment Variables section in the Permissions tab:

  • Verify the variable name matches what your code expects (for example, API_KEY in permissions should match event.env.API_KEY in code)
  • If the variable is linked to a connection, verify the connection is still valid and the credentials have not expired
  • If the variable is a custom value, re-enter the value to make sure it is correct

My tool times out

The tool took longer than 30 seconds to execute. Tools have a 30-second execution limit. Common causes:

  • The external API is slow or unresponsive
  • The tool is processing too much data in a single call
  • The tool is waiting for a resource that never responds

Consider breaking the work into smaller calls, adding timeouts to your HTTP requests, or paginating large result sets.

My tool returns empty or unexpected results

The API response format may not match what your code expects. Add logging to your code to inspect the raw response. Check:

  • Is the API endpoint correct?
  • Are you reading the right field from the response?
  • Does the API require specific headers or query parameters you are not sending?

Test with a simple case first (a known ID, a small query) to verify the connection works before handling complex inputs.

My published tool is not showing up in tool search

The tool may not have a clear enough description for discovery. Tool search uses the name and description to find matches. Update the description to be specific about what the tool does, what system it connects to, and what data it returns. Avoid generic descriptions like "Looks up data."

I want to undo a published version

Publish a previous version. Navigate to the tool's detail page, find the version you want to restore in the Version History, click Duplicate, then commit and publish the new draft. The tool is now running the restored code.

My environment variable value is not being picked up

Check the variable name for case sensitivity. Environment variable names are case-sensitive. If your code reads event.env.API_KEY, the variable must be named exactly API_KEY in the permissions panel, not api_key or Api_Key.

If the variable is linked to a connection, verify the connection is active and the linked field still exists.

Still need help? Contact your workspace administrator.