Skip to main content

Troubleshooting

Common issues and how to resolve them.

Connection Issues​

"Missing endpoint/token"​

The MCP server or CLI can't find your configuration.

Fix: Either set environment variables (JD_ENDPOINT, JD_TOKEN) or run jd init --global to create a config file. If using Docker, make sure the -e flags are passing the env vars correctly.

Check your current config with:

jd config show

"Authentication failed"​

Your API token is invalid or expired.

Fix: Generate a new token in Jira at Apps → AgentGate for Jira - Tokens. Tokens start with jfa_. If you recently regenerated, make sure you updated the token everywhere — MCP client config, environment variables, or config file.

"Connection timeout"​

The Forge app isn't responding.

Fix:

  1. Verify the endpoint URL is correct — copy it fresh from the Tokens page in Jira
  2. Check that the Forge app is installed on your Jira instance
  3. Forge apps occasionally need a few seconds to cold-start after inactivity — try again after a moment
  4. If the problem persists, check the JD_TIMEOUT setting (default: 30000ms)

"Project not found" or empty results​

The project key doesn't match any project in your Jira instance.

Fix: Check the project key is correct — project keys are case-sensitive (PROJ, not proj). Make sure your token's user has access to that project in Jira.

MCP Server Issues​

Claude Desktop doesn't show AgentGate tools​

The MCP server isn't connecting properly.

Fix:

  1. Check your claude_desktop_config.json for JSON syntax errors
  2. Make sure jd-mcp is installed globally (npm install -g @orbiscend/jd-mcp) and is in your PATH
  3. If using Docker, verify Docker is running
  4. Restart Claude Desktop after config changes
  5. Check Claude Desktop's MCP logs for error details

Tools appear but calls fail silently​

This usually means the environment variables aren't being passed to the MCP server.

Fix: Make sure your env vars are inside the "env" block of the MCP server config, not at the top level. Example:

{
  "mcpServers": {
    "agentgate-for-jira": {
      "command": "jd-mcp",
      "env": {
        "JD_ENDPOINT": "https://...",
        "JD_TOKEN": "jfa_..."
      }
    }
  }
}

CLI Issues​

jd: command not found​

The CLI isn't installed or not in your PATH.

Fix:

npm install -g @orbiscend/jd-cli

If already installed, check your Node.js global bin directory is in your PATH:

npm bin -g

prime returns empty or minimal data​

This usually means the project is new or has very few issues.

Fix: Verify the project key with jd issues list. Check that JD_PROJECT or the configured project matches your Jira project key exactly.

Tool Issues​

Pagination returns same results​

Use cursor-based pagination with next_page_token, not offset-based:

result = issues_list(limit: 10)
# Use result.nextPageToken for the next page
issues_list(next_page_token: result.nextPageToken)

Changes stuck in "pending"​

Changes require human approval before they're applied. They won't auto-apply.

Fix: Open the Review UI in Jira (Apps → AI Changes Review) and approve or reject the pending changes. Or use the CLI:

jd changes list --status pending
jd changes approve <change-id>

Change failed after approval​

A change was approved but couldn't be applied to Jira. Common causes: permission issues, the issue was modified by someone else, or a workflow transition isn't valid from the current status.

Fix: Check the error details:

jd changes show <change-id>

The applyError field describes what went wrong. Fix the underlying issue and retry, or cancel and re-propose.

Comment update not working​

When updating a pending comment, use the comment parameter, not proposed:

# Correct
changes_update(id: "chg-xxx", comment: { body: "Updated text" })

# Wrong
changes_update(id: "chg-xxx", proposed: { body: "Updated text" })

Permission Issues​

"You don't have permission to perform this action"​

Your token's user doesn't have the required Jira permissions.

Fix: AgentGate respects Jira's native permission scheme. If the user can't perform an action in Jira directly, they can't propose it through AgentGate either. Ask your Jira admin to grant the appropriate project role.

Can't see the Tokens page in Jira​

The Tokens page is accessible to Jira site admins.

Fix: Ask your Jira site admin to either grant you access or generate a token for you.

Docker Issues​

"Unable to pull image" or rate limit errors​

Docker Hub may rate-limit anonymous pulls.

Fix: Authenticate with Docker Hub (docker login), or use the npm installation method instead:

npm install -g @orbiscend/jd-mcp

Docker container exits immediately​

This is normal. The MCP server communicates over stdin/stdout and is designed to be launched by an MCP client, not run standalone.

Fix: Configure your MCP client to launch the Docker container as shown in MCP Setup. Don't run it directly in a terminal.

Getting Help​

If you're stuck:

  1. Check this documentation at docs.orbiscend.com
  2. Email support@orbiscend.com
  3. Visit the AgentGate Marketplace listing for the latest information