Skip to content

Troubleshooting

"No path from X to Y"

The workflow graph has no transition path between the two statuses. Check transition.yaml:

  • Ensure all intermediate steps are defined (e.g., Open → In Progress → Done, not just Open → Done if the workflow requires it).
  • Verify the from/to status names match exactly what Jira uses (case-sensitive).

Rate Limiting / Slow Execution

When Jira returns HTTP 429 (or 503 with Retry-After), the tool waits as long as Jira asks, pausing all requests together, and then retries. Rate-limited requests get their own retry budget, so a transition is never lost to a 429 unless the limit persists.

If the log shows frequent rate limits, or rows fail with Jira rate limit exceeded, reduce concurrency and allow more patience in settings.toml (in [default] or the active environment's section):

JIRA_MAX_CONCURRENCY = 5
PHASE2_WORKERS = 5
JIRA_RATE_LIMIT_MAX_RETRIES = 20
JIRA_RATE_LIMIT_MAX_WAIT = 600     # seconds

Rows that failed can be retried by running Phase 2 again on the same file; rows already in their target status are skipped.

Authentication Failures

Authentication failed: ...

Check your KeePass config:

  • KEEPASS_DB path exists and is readable.
  • KEEPASS_KEY points to the correct key file.
  • KEEPASS_ENTRY matches the entry name exactly (case-sensitive).

No Issues Found

⚠️  No issues found matching JQL
  • Test your JQL directly in Jira's issue navigator.
  • Ensure the authenticated user has permission to view those issues.

Excel Dropdown Not Working

If target_status dropdowns are missing after opening the plan:

  • Open the file in Excel (not a third-party spreadsheet app).
  • Enable editing if prompted by the Protected View banner.

Logging

Enable detailed logging to diagnose unexpected behaviour:

# Watch the log file in real time
tail -f jira_transition_runner.log

Or pass a custom logging config:

jira-runner --log-config debug_logging.yaml --project PROJ ...

Where debug_logging.yaml sets the console handler level to DEBUG.

Missing Transitions in Results

If a row shows FAILED with no transition found:

  1. Check the workflow_name column — ensure that workflow is defined in transition.yaml.
  2. Verify the issue's current status in Jira matches what the plan recorded (it may have changed since Phase 1).
  3. Confirm the Jira transition ID is correct for your Jira instance.