Troubleshooting

Common Issues

- Ensure you're using API tokens, not your account password - Verify the token hasn't expired - Check that JIRA_USERNAME / CONFLUENCE_USERNAME is your email address

- Verify your Personal Access Token is valid and not expired - For older Confluence servers, try basic auth with CONFLUENCE_USERNAME and CONFLUENCE_API_TOKEN (where token is your password)

mcp-atlassian uses the OS native trust store by default (via truststore), so certificates signed by enterprise CAs installed in Windows Certificate Store, macOS Keychain, or the Linux system CA bundle are trusted automatically.

If you still see SSL errors with **self-signed** certificates that
are **not** in the OS trust store, disable verification:

```bash
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```

To disable the OS trust store integration (fall back to the bundled
certifi CA bundle):

```bash
MCP_ATLASSIAN_USE_SYSTEM_TRUSTSTORE=false
```

Ensure your Atlassian account has sufficient permissions to access the spaces/projects you're targeting.

Debugging

Enable Verbose Logging

# Standard verbose
MCP_VERBOSE=true

# Debug level (includes request details)
MCP_VERY_VERBOSE=true

# Log to stdout instead of stderr
MCP_LOGGING_STDOUT=true

View Logs

macOSWindows

bash tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

cmd type %APPDATA%\Claude\logs\mcp*.log | more

MCP Inspector

Test your configuration interactively:

# With uvx
npx @modelcontextprotocol/inspector uvx mcp-atlassian

# With local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-atlassian run mcp-atlassian

Debugging Custom Headers

Verify Headers Are Applied

1. Enable debug logging:

   MCP_VERY_VERBOSE=true
   MCP_LOGGING_STDOUT=true
   

2. Check logs for header confirmation:

   DEBUG Custom headers applied: {'X-Forwarded-User': '***', 'X-ALB-Token': '***'}
   

Correct Header Format

# Correct
JIRA_CUSTOM_HEADERS=X-Custom=value1,X-Other=value2

# Incorrect (extra quotes)
JIRA_CUSTOM_HEADERS="X-Custom=value1,X-Other=value2"

# Incorrect (colon instead of equals)
JIRA_CUSTOM_HEADERS=X-Custom: value1,X-Other: value2

# Incorrect (spaces around equals)
JIRA_CUSTOM_HEADERS=X-Custom = value1

Note

Header values containing sensitive information are automatically masked in logs.

Authentication Errors

Cause: Invalid or expired API token.

**Fix:**
1. Verify your API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Ensure `JIRA_USERNAME` matches the email associated with the token
3. Check that the token hasn't been revoked

```bash
# Test your credentials
curl -u "your.email@example.com:your_api_token" \
  "https://your-instance.atlassian.net/rest/api/2/myself"
```

Cause: Invalid PAT or PAT doesn't have required permissions.

**Fix:**
1. Create a new PAT in your Jira/Confluence profile settings
2. Ensure the PAT has sufficient permissions for the operations you need
3. Note: Server/DC limits PAT count (max 10 per user)

```bash
# Test PAT authentication
curl -H "Authorization: Bearer your_pat_token" \
  "https://jira.your-company.com/rest/api/2/myself"
```

Cause: Your account doesn't have permission for the requested operation.

**Fix:**
- Verify your Jira/Confluence project permissions
- For write operations, ensure your account has edit permissions
- For admin-only fields, you may need project admin access
- Check if `READ_ONLY_MODE=true` is blocking write tools

Cause: OAuth access token has expired and refresh failed.

**Fix:**
1. Re-run the OAuth setup: `mcp-atlassian --oauth-setup`
2. Ensure your app has `offline_access` scope for refresh tokens
3. Check if the OAuth app is still active in your Atlassian developer console

Field and Data Errors

Cause: Custom field ID doesn't exist or isn't available on the issue type.

**Fix:**
1. Use `jira_search_fields` to find the correct field ID
2. Check if the field is available on the target issue type's screen
3. Custom field IDs differ between Cloud and Server/DC instances

```json
jira_search_fields: {"keyword": "story points"}
```

Cause: The specified issue type doesn't exist in the project.

**Fix:**
- Use `jira_get_all_projects` to see available issue types per project
- Issue type names are case-sensitive
- Some issue types (e.g., "Epic") may require specific project configurations

Cause: File exceeds the 50MB attachment limit.

**Fix:**
- MCP Atlassian limits inline attachment downloads to 50MB
- For larger files, access attachments directly via the Jira/Confluence web UI
- Consider compressing files before uploading

Rate Limiting

Cause: You've exceeded the Atlassian API rate limit.

**Fix:**
- Atlassian Cloud: ~100 requests per minute per user (varies)
- Server/DC: depends on instance configuration
- Add delays between bulk operations
- Use batch tools (`jira_batch_create_issues`, `jira_batch_get_changelogs`) instead of individual calls
- Consider using `ENABLED_TOOLS` to limit which tools are available

Connection Issues

Cause: Server/DC instance uses a self-signed or internal CA certificate.

**Fix:**
```bash
# Disable SSL verification (not recommended for production)
JIRA_SSL_VERIFY=false
CONFLUENCE_SSL_VERIFY=false
```

For mTLS (mutual TLS) authentication:
```bash
JIRA_CLIENT_CERT=/path/to/client-cert.pem
JIRA_CLIENT_KEY=/path/to/client-key.pem
```

Cause: Atlassian instance is unreachable or slow to respond.

**Fix:**
- Default timeout is 75 seconds
- Increase timeout for slow instances:
```bash
JIRA_TIMEOUT=120
CONFLUENCE_TIMEOUT=120
```
- Check if a proxy is required:
```bash
HTTPS_PROXY=https://proxy.example.com:8443
```

Getting Help

• Check GitHub Issues for known problems
• Review SECURITY.md for security-related concerns
• Open a new issue with debug logs if the problem persists