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.

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.

Next steps​