Skip to main content

Troubleshooting

Last updated on

Use this page to resolve errors related to startup, authentication, and tool-calls. For more information on Hosted MCP OAuth failures, see Harness Hosted MCP. If sign-in fails at your SAML or OIDC Identity Provider, add the MCP-specific ACS URL or redirect URI as described in Single Sign-On (SSO) for Harness MCP.

Debug with MCP Inspector​

Use the MCP Inspector to debug the server interactively:

npx @modelcontextprotocol/inspector npx harness-mcp-v2

The Inspector displays a URL you can open in your browser to inspect tool calls and responses.

Common issues​

HARNESS_ACCOUNT_ID is required when the API key is not a PAT

Your API key is not in PAT format (pat.<accountId>.<tokenId>.<secret>), so the account ID cannot be auto-extracted. Set the HARNESS_ACCOUNT_ID environment variable explicitly.

npx ENOENT or node: No such file or directory when using GUI clients

GUI apps (Cursor, Claude Desktop, Windsurf, VS Code) do not inherit your shell's PATH. Use absolute paths for the command and explicitly set PATH in the env block of your MCP config. Run 'which npx' and 'which node' in a terminal to find the correct paths.

Unknown resource_type error from tools

The resource type is misspelled or filtered out via HARNESS_TOOLSETS. Call harness_describe (with optional search_term) to discover valid resource types.

Missing required field for path parameter

A project or org scoped call is missing identifiers. Set the HARNESS_ORG and HARNESS_PROJECT environment variables, or pass org_id and project_id per tool call.

Read-only mode is enabled and write operations are not allowed

HARNESS_READ_ONLY=true blocks create, update, delete, and execute operations. Set HARNESS_READ_ONLY=false if write operations are intended.

Pipeline run fails with unresolved required inputs

Your inputs did not cover all required runtime placeholders. Fetch the runtime_input_template first, then supply missing keys via inputs or use input_set_ids for structural inputs.

HARNESS_BASE_URL must use HTTPS

The server enforces HTTPS by default. If you need HTTP for local development, set HARNESS_ALLOW_HTTP=true.

Operation declined by user

The user declined the elicitation confirmation dialog. Verify the operation details and retry if intended.

HTTP mcp-session-id header is required or Session not found

Send an initialize request first to create a session, then include the mcp-session-id header on all subsequent POST, GET, and DELETE requests to /mcp. Sessions expire after 30 minutes of idle time.

VS Code stuck in a session 404 or 401 reconnect loop

VS Code may repeatedly log a cycle like this in the MCP server output and never recover:

Connection state: Running
Connection state: Error 404 status sending message to https://mcp.harness.io/mcp:
{"jsonrpc":"2.0","error":{"code":-32000,"message":"Session not found. Send an
initialize request to start a new session."},"id":null}; will retry with new session ID

You may also see a 401 response with a www-authenticate header that never resolves into a completed sign-in prompt.

This is caused by a known VS Code behavior (microsoft/vscode#253854): VS Code caches the dynamic authentication provider for an MCP server so it does not re-prompt you on every connection. When that cached authentication or registration goes stale, the server returns a 401 or 404, and VS Code retries with the same stale state instead of starting a fresh OAuth flow.

Resolution: Remove the cached dynamic authentication provider, then reconnect.

  1. Open the Command Palette and run MCP: Remove Dynamic Authentication Provider (or open the Account menu in the lower-left corner and sign out of the Harness dynamic authentication entry).
  2. Reload the window or restart the MCP server.
  3. Reconnect and complete the OAuth sign-in flow again.

You do not need to reinstall VS Code or clear its full local state to resolve this.

Next steps​