> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Jira troubleshooting

> Debug Jira connection, issue creation, field mapping, and project access problems.

<Warning>
  The Jira integration is in **closed beta**. If you're not yet enrolled and are seeing issues, contact [support@open.cx](mailto:support@open.cx) for access.
</Warning>

Before debugging, have this ready:

* Your Atlassian Cloud <Tooltip tip="The full domain of your Jira Cloud instance — e.g. acme.atlassian.net.">domain</Tooltip> and the email used for the <Tooltip tip="A long-lived credential generated in your Atlassian account settings. Bound to the user whose email you provide.">API token</Tooltip>.
* The specific recommendation or insight you tried to push to Jira.
* Access to [Settings → Integrations](https://platform.open.cx/settings/integrations) in your OpenCX dashboard.

<Tip>
  Re-run **Verify** in [Settings → Integrations](https://platform.open.cx/settings/integrations) → Jira as your first step. Most issues are credential or permission related.
</Tip>

## Common scenarios

Jump to the symptom that matches what you're seeing.

### **"Failed to verify credentials" on save**

<Tooltip tip="Usually caused by entering a partial domain, an expired or revoked API token, or an email that doesn't match the token owner.">Likely cause</Tooltip>: wrong domain format, expired token, or mismatched email.

**Fix:**

* Use the **full Atlassian domain** — e.g. `acme.atlassian.net`. The domain must include `atlassian` in the hostname.
* Regenerate the API token in [Atlassian account settings](https://id.atlassian.com/manage-profile/security/api-tokens) if the current one may have been revoked.
* Confirm the email matches the Atlassian account that generated the token.

### **Connected but no issues appear in Jira**

<Tooltip tip="The connection verified, but pushing a recommendation or insight doesn't create an issue. Usually a project access or issue type problem.">Likely cause</Tooltip>: the API token's account lacks access to the target Jira project, or the default issue type doesn't exist in that project.

**Fix:**

1. Confirm the Atlassian account behind the token has access to the target project in Jira.
2. In OpenCX, check that the **default project** and **default issue type** are set in [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations).
3. Navigate to [**AI Recommendations**](https://platform.open.cx/reports/voice-of-customer) or [**Customer Insights**](https://platform.open.cx/reports/voice-of-customer) and explicitly push an item to Jira. Issues are created on-demand — they are not generated automatically in the background.

<Info>
  Issues are created when you push a recommendation or insight to Jira from the OpenCX dashboard. If you've connected Jira but haven't pushed anything yet, no issues will appear.
</Info>

### **Wrong project or issue type on created issues**

<Tooltip tip="The issue landed in the wrong Jira project or used the wrong type (e.g. Task instead of Bug).">Likely cause</Tooltip>: organization defaults overriding per-issue selection.

**Fix:** check the defaults in [Settings → Integrations → Jira](https://platform.open.cx/settings/integrations). When pushing a recommendation, use the project and issue type override to target a different project.

### **Field mappings not appearing on issues**

<Tooltip tip="Custom fields you mapped aren't populated on the created Jira issue.">Likely cause</Tooltip>: mapping not active, field ID mismatch, or the Jira field isn't available on the target issue type's screen.

**Fix:**

1. Open the field mappings in your Jira integration settings and confirm the mapping is saved.
2. In Jira, confirm the custom field is added to the **screen** for the issue type you're creating. Jira hides fields that aren't on the issue's screen, even if the API sets them.
3. Re-push a recommendation to test — field mappings apply at creation time only.

### **Project or issue type missing from the selection**

<Tooltip tip="The dropdown in OpenCX doesn't show all your Jira projects or issue types.">Likely cause</Tooltip>: the API token's account doesn't have access to that project, or the issue type isn't available for the selected project.

**Fix:**

* Confirm the Atlassian account has at least **browse** permission on the project.
* Issue types are loaded per project — switch to the correct project to see its available types.

### **None of the above**

If your issue doesn't match any scenario here, contact [support](mailto:support@open.cx) with:

* Your OpenCX organization name.
* The Atlassian domain you're connecting to.
* The specific action you took and the error message (or lack of expected result).

## Limits and timing

|                          | Value                                        |
| ------------------------ | -------------------------------------------- |
| **Issue creation**       | On-demand (when you push from the dashboard) |
| **Verification timeout** | 10 seconds                                   |
| **Projects loaded**      | Most recent projects from the Atlassian API  |
| **Field mappings**       | Applied at issue creation time only          |
| **Jira Cloud only**      | Server and Data Center are not supported     |

<Note>
  OpenCX does not retry failed issue creation automatically. If an issue fails to create (e.g. due to a temporary Jira outage), push the recommendation or insight again once Jira is back.
</Note>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Connect Jira" icon="plug" href="/integrations/jira/connect">
    Re-verify credentials and check field mapping setup.
  </Card>

  <Card title="Issue Flow" icon="diagram-project" href="/integrations/jira/issue-flow">
    How issues are created from recommendations, insights, and conversations.
  </Card>

  <Card title="Overview" icon="list-check" href="/integrations/jira/overview">
    Capabilities and observability features.
  </Card>

  <Card title="Handoff" icon="user-group" href="/handoff/introduction">
    Global handoff rules and escalation settings.
  </Card>
</CardGroup>