Skip to main content
Use this page to diagnose common issues when setting up or using Octoparse MCP Server.

​
Authentication issues

​
Missing or invalid API key

You may see an authentication error if the MCP server cannot find a valid Octoparse API key. Common symptoms:
Check that your API key is valid and has not been deleted or regenerated. If you use an environment variable, confirm that it is available in the same shell or runtime that starts the MCP server.
If the output is empty, set the API key again before starting the server.
Do not commit API keys to Git, scripts, screenshots, shared logs, or public issue reports.

​
API key works in one terminal but not in the MCP client

Some MCP clients do not inherit environment variables from your interactive terminal. If the MCP server works when started manually but fails inside an MCP client, check the client configuration and make sure the API key is passed to the server process. Restart the MCP client after updating environment variables.

​
Server startup issues

​
MCP server does not start

If the MCP server fails to start, check the command, working directory, Node.js version, and environment variables. Run the server command directly in a terminal first. This helps separate MCP client configuration issues from server runtime issues.
Make sure the command used by your MCP client matches the command that works in your terminal.

​
Command not found

If the MCP client reports that the server command cannot be found, use an absolute path or confirm the package is installed. A command may work in your shell but fail in the MCP client if the client does not use the same PATH.

​
Task access issues

​
Task not found

You may see a task-not-found error if the task ID is incorrect or the authenticated account does not have access to the task. Check that:
  • The task ID is copied correctly.
  • The task belongs to the authenticated Octoparse account.
  • The task has not been deleted.
  • The API key belongs to the correct workspace or account.

​
No accessible tasks returned

If task search returns no results, verify the API key and account access first. Then try a broader search query or list tasks without a keyword filter.

​
Task execution issues

​
Task fails to start

A task may fail to start if the task definition is unsupported, the task is already running, or the account does not have permission to run it. Check the task in Octoparse first, then retry from the MCP client. If the task was created with an older workflow, rebuild or update the task in the current Octoparse app before running it through automation.

​
Execution starts but no data is returned

If execution succeeds but export returns no data, check whether the task has finished and whether the selected run or lot contains data. Common causes:
  • The task is still running.
  • The selected lot ID does not contain data.
  • The task completed but matched no records.
  • Export was requested before the run finished.

​
Export issues

​
Export fails

If export fails, verify that the task has completed and that the export format is supported by the tool you are using. If the export command or tool accepts a lot ID, make sure the lot ID belongs to the same task and run history.

​
Empty export file

An empty export usually means the selected run has no extracted records, or the export was requested before extraction finished. Check task history first, then export again using the correct run or lot.

​
Rate limits and transient failures

If a request fails intermittently, retry after a short delay. Network issues, task queue delays, or temporary backend errors may cause transient failures. For repeated failures, capture:
  • The MCP client name and version
  • The MCP server version
  • The exact tool call or prompt
  • The task ID
  • The error message
  • Whether the same task works in Octoparse directly
Remove API keys, access tokens, cookies, and personal data before sharing logs.

​
What to provide when reporting an issue

Include the following information:
  • MCP client name
  • MCP server version
  • Operating system
  • Node.js version
  • Tool name that failed
  • Exact error message
  • Task ID or a sanitized example
  • Whether the task works in Octoparse outside MCP