Possible issues with Jira Cards and Jira add-on

The Jira Cards app is installed, but your Miro Team isn't connected to Jira.

Please follow this installation guide: How to set up and to uninstall Jira Cards. If you're not a team admin, ask the admin to do so. 

Request to Jira ... failed: Timeout has occurred / Unknown host / Connection refused

Jira is only accessible on your intranet (you are using the wrong IP addresses to communicate to the Jira system).

Be sure to allowlist our IP address, domains, and subdomains to provide our integration with the necessary access level. 

If you're on Jira Server and on an older version, double-check that no Dark Features block access for Miro.

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Application link in your Jira is not configured correctly

- You have missed some steps in the link or webhook configuration

- You have installed Jira Addon instead of configuring the link for Jira Cards.

Try installing the Jira Cards integration from scratch. 

If you chose to create the webhook manually try creating it automatically.

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Application link in your instance of Jira is not configured correctly, or token has expired. Check the application link and reconnect the integration.

- The Application link in Jira was reconfigured

- Token has expired

- Token has been revoked

Make sure your Application link is configured correctly and try to Connect Miro to Jira Cards again.

If you are using a highly-protected Jira or you are using a proxy, be sure to allowlist our IP address, domains, and subdomains to provide our integration with the necessary access level. 

If you're on Jira Server and on an older version, double-check that no Dark Features block access for Miro.

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Your app link asks for more values than just URL, Consumer Key, Consumer Name, Public Key

You're looking at the Outgoing Authentication tab of the configuration menu.

- Switch to the Incoming Authentication. Outgoing Authentication does not require configuration.

- If you cannot skip the step, add any temporary values. You will be able to remove them later: when on the page with your Application links' list click to Edit Miro Cards link and remove the temporary values. 

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Jira URL is not valid /
Enter Jira base URL /
Bad request. Deserialization.

Your Jira is on a private network / your company firewall blocks external network connections.

Add our NAT Gateway IP addresses (and ports) to your allowlist. 
*Note that if you check our IP addresses using nslookup, the results will return our load balancer's addresses which may vary and change over time.

You use a proxy / Your external and internal Jira URLs do not match.

Be sure to fill in the Jira URL field with the address that we can access, so please configure a reverse proxy allowing us access and/or follow the steps from this Atlassian guide. With this solution, the integration will be able to connect and forward requests successfully between your Jira and Miro if your External and Internal URLs are different.
You may also want to prolong the timeout value on your proxy server.
The list of endpoints can be found here: Jira Cards FAQ

There is an issue with your SSL certificate (self-signed certificates are not supported).

Check the active SSL certificate on the Jira server. This tool might be helpful: enter your Jira URL and see the results of the connection check.
Example: the certificate may be correct (the Certificate in green) but the server certificate chain may be incomplete (Key exchange in yellow) therefore our system gets a response that the certificate needs to be updated.
Refer to this site to resolve issues.

Your Jira is under SSO (may also result in Incoming authentication is not configured correctly error).

Please make sure that your SSO process is not applied to the connection requests of our integration. To achieve that, the following endpoints must be excluded from SSO processes:

POST {JIRA_URL}/plugins/servlet/oauth/request-token
POST {JIRA_URL}/plugins/servlet/oauth/access-token
GET {JIRA_URL}/rest/api/2/serverInfo

Unexpected behavior during installation

You use Jira versions 6.4 or lower.

Our cards will not work with these versions due to this Jira bug. Please update your Jira to the latest version.

App authorisation failed. Please try to authorise the app again. 

A momentary loss of connection. Click to Connect again. 

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Jira error: "You don't have permissions to create Webhook 'Miro'."

You don't have Admin rights on Jira. Please ask your Jira Admin to upgrade your role to Admin so you could set up the integration.

Request to Jira failed: PKIX path building failed: unable to find valid certification path to requested target

There is some issue with your server certificate.
 
As a solution, we suggest that you contact your IT Department and ask them to check the certificates on your side (reload the web servers; make sure that certificates are publicly trusted, etc.). 

Inability to authorize in Jira via Miro.
Error: exceptions 
(e.g. io.netty.handler.timeout.ReadTimeoutException)

This may occur due to misconfiguration of the Jira infrastructure when the infrastructure setup indicates support for HTTP/2 protocol, but no data transfer takes place when attempting to use it. Check your HTTP/2 settings in your web server's configuration files to ensure they are set up correctly.

If needed, temporarily disable HTTP/2 support in your server configuration to ensure backward compatibility and uninterrupted service until the issue is resolved.

Jira Cards aren't updating

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

You are using a manual webhook.

Please disable the integration and reconnect it using an automatic webhook. If everything is working fine with an automatic webhook, it means that a manual one was configured incorrectly.

Also, refer to How to Set Up WebHook for Jira Cards. 

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

If you are using an automatic webhook:

The first troubleshooting step is to reconnect the integration. If it doesn't help, there might be several reasons why the Jira Cards aren't alive anymore:

- a Miro board was moved/downloaded via backup to a team from another one

- the non-updating Jira issues were moved from one project to another one on Jira's side

- you do not have access to the projects in which the Jira issues are located

- the non-updating cards aren't located in the same Jira instance that you’re currently using in your browser

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Jira cards stopped updating without any changes on your end and when attempting to reconnect the Application link in your Jira is not configured correctly.

The error message can appear when Miro is unable to request a connected Jira due to an authorization error. This can happen if the user who set up the integration revokes their token or if Jira is somehow configured with a short lifetime of the issued token, so it simply becomes invalid after this time and has to be reconnected to get a new valid authorization token with which Miro accesses Jira.

The Edit card option returns a blank window

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

You use Jira ver. 7.6 and higher.

Due to security reasons, Atlassian may not allow the content to be embedded in iFrames, which might also affect pop-up windows for editing your Jira cards. You may use these instructions as a workaround.

Unable to add Jira cards

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

You have created a manual webhook and have not saved the setup information.

Check if the field Jira URL is filled out in the Miro Settings. Be sure to click Connect

The Edit icon is not displayed

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

You use Jira server versions 7.6 or higher.

Edit icon may not be displayed due to a security update in this version.

Your profile is not allowed to edit the Jira issue in question.

Check if you can access the edit mode having opened the issue on the Jira side.

You get the message: You are not logged in and do not have the permissions required to act on the selected issue as a guest. Please log in

Due to the way our integration uses cookies your Jira might not allow you to log in from this page.

Log into Jira in another browser tab.
Be sure to check that 3rd-party cookies are allowed in your browser.

Your Jira is under SSO and your IDP does not allow authentication through iframes.

If you're working in the Miro desktop app we recommend switching over to the Miro browser version at miro.com.

No option to convert/create a Jira card in Miro when you choose some particular Projects:

- no data in the Issue type field

- the Convert/Create button is inactive

You do not have access to the Project in Jira. Check if you can be granted access.

Unable to create Jira issue when trying to convert/create a new Jira card: 

You do not have permission to create Jira issues.

Please contact your Jira Admin and ask them to grant you the necessary permission on the Jira's side. This is how it should look like:

Some custom fields are not shown in the Convert to Jira Issue/Edit Jira Issue menu

Can’t create Jira issue. Required fields (...) are not supported error when creating a Jira issue within Miro

Fields are not enabled on the board Jira Cards picker.

Use our in-app Jira picker to set up custom fields following steps from this guide.

If the Select fields to display on cards does not show custom fields of your Jira, it is possible that some of the Screens configured for the projects of your Jira instance shield the fields from Miro.

Go to Project settings > Screens > Default Screen Scheme and check if the needed fields are allowed.

Miro does not support complex data type fields.

Miro supports basic custom fields but no complex ones. Configure Jira card fields and remove those fields that are not supported.

You cannot choose the Reporter when editing/creating a Jira card

There is no Reporter field in the Jira's Create metadata: the field is unavailable on the Jira Create screen for the selected project.

Go to Project settings > Screens and check if the Reporter field is present in the Create screen.

You do not have the necessary permission to set the reporter for issues in the selected project. 

Ask the Jira Admin to check your access levels and ensure you are permitted to set/change the Reporter field in the selected project. To do so, they need to sign in to Jira > go to Settings > Issues > Permission schemes > and check the Modify Reporter field (please add the Application access: Any logged in user in case you don't have it on the list):

The reporter field is not editable for audit trail and is set to who created the issue.

The field being unavailable is expected behaviour.

Some fields are displayed in an edit mode of a card but do not show up on the Jira Cards on the boards

Miro doesn't receive updates from Jira.

• Switch to another network
• Reconnect the integration

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Jira is not available error in Jira Cards App Settings

1. Ask the Team Admin to disable and re-connect the integration.

2. Your Jira is under protection (firewall, security blockers, etc.) and cannot be reached by Miro.

If at the same time Jira Cards sync between Miro and Jira, it means that your Jira can send us webhooks. That’s why you can see the updates on your boards.

As a solution, we suggest that you discuss the issue with your IT Department and ask them to double-check that Miro is properly allowed. 

If you're on Jira Server and on an older version, double-check that no Dark Features block access for Miro.

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

Jira webhook issues error in Jira Cards App Settings

- You changed/deleted a webhook on the Jira's side
- Miro receives the 'Bad request' response from your Jira

When you use Ctrl + V (for Windows)/Cmd + V (for Mac) to paste a Jira issue link on the board, it does not get converted into a Jira Card but gets pasted as a URL

The board is still loading. May happen on larger boards or boards will larger images or PDF documents. 

Please wait at least 10 seconds after you open the board and let the board fully load. Then try to paste the link again.

The description is not visible on Jira Cards on the board

The description of a card may be hidden if you zoom out. To see the description, you may need to expand the card or zoom in (the description becomes partly visible with a triple board zoom)

"Showing 0 of 0 matching sprints" when trying to search & find available sprints

1. It happens when you have no active/future sprints (all of them are closed/completed). 

2. Your filter in Jira doesn't include any projects. Please add a needed project to the JQL for the board filter - thus, the sprints will appear, both in Jira and in Miro.

Applicable to OAuth 1.0. (Jira Server & Data Center) only.

SSL connection with ... failed

The error means that Miro doesn't have access to your Jira.

Contact your Miro Team admins and ask them to check if your Jira Base URL field in the Jira Cards settings contains the address we can connect to.

Ensure you have the "Browse users" permission set at the global level in Jira. Learn more about how to manage global permissions. 

Unfortunately, because our plugin uses cookies, Jira will not allow you to log in from this page.

Log into Jira in another browser tab.

After clicking the Install button on the add-on page you might see the following error:

A momentary loss of connection.

In this case, simply retry to install a minute later.

During or after the configuration of the Jira Addon you are unable to proceed to the next page at some step

Something in your cookies or cache stops the process.

Clear your browser's memory for the domain atlassian.com and try again.

After the successful installation, your Jira users that are not registered with Miro are seeing the Miro login menu instead of the attached board.

Jira policies block some of the plugin functionalities. 

Unfortunately, this behavior is caused by the most recent Jira API update and cannot be amended at the moment.

The Addon does not remember your authorization and keeps asking you to log in every time.  

When you try to add boards to a Jira issue, a board picker shows a "Sorry, integration is unavailable" error.

The third-party cookies are blocked in your browser.

As a solution, follow the instruction on how to enable the cookies in your browser. This mostly happens with Mozilla and Safari due to their new security policies.
For Safari, this solution can also help.