Skip to content
atlcli

Troubleshooting

Troubleshooting

Section titled “Troubleshooting”

Common issues and solutions for atlcli.

Authentication Errors

Section titled “Authentication Errors”

401 Unauthorized

Section titled “401 Unauthorized”
Error: Authentication failed (401)

Causes:

  • Invalid or expired API token
  • Wrong email address
  • Incorrect instance URL

Solutions:

  1. Regenerate API token at Atlassian Account
  2. Verify email matches your Atlassian account
  3. Check URL includes https://
Terminal window
atlcli auth init  # Re-initialize credentials

403 Forbidden

Section titled “403 Forbidden”
Error: You don't have permission (403)

Causes:

  • Account lacks required permissions
  • Project/space access restricted

Solutions:

  1. Verify account has access to the project/space
  2. Contact your Atlassian admin for permissions

Connection Errors

Section titled “Connection Errors”

Network Timeout

Section titled “Network Timeout”
Error: Request timeout

Solutions:

  1. Check internet connection
  2. Verify Atlassian status at status.atlassian.com
  3. Try again with --verbose for details

SSL Certificate Error

Section titled “SSL Certificate Error”
Error: self signed certificate in certificate chain
Error: unable to verify the first certificate
Error: Unable to verify certificate

Causes:

  • On-premises Jira/Confluence Data Center using a self-signed certificate
  • Instance certificate issued by an internal / enterprise Certificate Authority not in the system trust store
  • Corporate TLS-intercepting proxy

Solutions:

  1. Point atlcli at your internal CA (recommended). Re-run login with --ca-file:

    Terminal window
    atlcli auth login --bearer --site https://jira.company.internal \
      --token YOUR_PAT --ca-file /etc/ssl/certs/company-ca.pem

    The CA file path is persisted on the profile and used for every subsequent request. See TLS and Self-Signed Certificates.

  2. Install the CA into your system trust store (alternative) — appropriate when many tools on the machine need it, not just atlcli.

  3. Check for a corporate TLS-intercepting proxy — if traffic is being MITM’d by a proxy, you’ll need its root CA from your IT team.

  4. Last resort: skip verification with --insecure — only appropriate for disposable test instances. Never use in production, as it disables protection against MITM attacks:

    Terminal window
    atlcli auth login --bearer --site https://jira.test.local --token YOUR_PAT --insecure

Confluence Issues

Section titled “Confluence Issues”

Sync Conflicts

Section titled “Sync Conflicts”
Conflict: file.md was modified both locally and on Confluence

Solutions:

  1. Pull latest changes: atlcli wiki docs pull
  2. Merge manually
  3. Force push: atlcli wiki docs push --force

Page Not Found

Section titled “Page Not Found”
Error: Page not found (404)

Causes:

  • Page was deleted on Confluence
  • Page ID changed

Solutions:

  1. Re-pull directory: atlcli wiki docs pull
  2. Remove stale local file

Jira Issues

Section titled “Jira Issues”

Invalid JQL

Section titled “Invalid JQL”
Error: Invalid JQL query

Solutions:

  1. Check JQL syntax
  2. Verify field names exist
  3. Quote values with spaces
Terminal window
# Correct
atlcli jira search --jql "status = 'In Progress'"


# Wrong
atlcli jira search --jql "status = In Progress"

Issue Type Not Found

Section titled “Issue Type Not Found”
Error: Issue type 'Bug' not found in project

Solutions:

  1. List available types: atlcli jira field list --type issuetype
  2. Use correct type name for your project

Field Not Editable

Section titled “Field Not Editable”
Error: Field 'status' cannot be set directly

Solutions:

  • Use transitions for status changes
  • Some fields are read-only
Terminal window
atlcli jira issue transition --key PROJ-123 --to "Done"

Performance

Section titled “Performance”

Slow Commands

Section titled “Slow Commands”

Solutions:

  1. Use --limit to reduce results
  2. Use more specific JQL
  3. Check network latency

High Memory Usage

Section titled “High Memory Usage”

Solutions:

  1. Process results in batches
  2. Use --json and pipe to jq for large datasets

Debug Mode

Section titled “Debug Mode”

Enable verbose output:

Terminal window
ATLCLI_LOG_LEVEL=debug atlcli jira search --assignee me

Getting Help

Section titled “Getting Help”
  1. Check this documentation
  2. Search GitHub Issues
  3. Open a new issue with:
    • atlcli version
    • Command that failed
    • Full error message
    • Steps to reproduce
Section titled “Related Topics”
Jira and Confluence are trademarks of Atlassian Corporation Plc. atlcli is not affiliated with, endorsed by, or sponsored by Atlassian.