Troubleshooting

This document helps you troubleshoot the most common issues you may encounter while installing or deploying an app to Jira.

Most deployment errors can be fixed automatically. When a problem occurs during deployment, you'll see an Auto Fix button. Click it and the AI will analyze the error and attempt to resolve it automatically.

If the issue isn't resolved after three attempts, some problems require manual action because they depend on:

• your Atlassian account settings (e.g., API tokens)

• Jira permissions

• or Atlassian Forge availability

Here you'll find clear steps to resolve these issues manually and continue the setup process.

Auto Fix

When a deployment error occurs, AI Apps Builder can attempt to fix it automatically.

1. Click the Auto Fix button, and the error is automatically sent to the AI.

2. The AI analyzes and fixes the problem. To apply changes, redeploy your app in Jira.

API Token Issues

This type of error occurs when an invalid or expired API token is provided. If the token is invalid or expired, the app cannot be registered, installed, or deployed.

How to fix it?

1. Open Atlassian Account Settings:

   • Go to https://id.atlassian.com/manage-profile/security/api-tokens

   • Or click the button under the API token input field in the app.

2. Click Create API token.
   Warning Make sure to use Create API token, not Create API token with scopes.

3. 

   Set a name and an expiration date for the token. These values do not affect the app’s functionality, so you can choose any values you prefer.

   

4. After the token is created, copy it immediately.

   warning Once you click Done, you will not be able to copy this token again.

   

5. Paste the new token into the API token input field in the app.

6. Click Test connection to verify that the token is valid.

Jira Permission Issues

This type of error occurs during the app installation phase and indicates that you do not have sufficient permissions to install the app in the selected Jira instance.

How to fix it?

There are several ways to resolve this problem:

1. Select a different Jira instance
   Change the Jira instance in the Atlassian domain input field to one where you have administrator access.

2. Request temporary admin access
   Ask a Jira administrator to grant you temporary admin permissions so you can install the app yourself.

3. Ask an admin to install the app for you
   Generate the installation link (see How to Move Forge Apps Built with AI Apps Builder to Another Jira Site) and send it to the Jira administrator.
   The admin can use this link to install the app directly.

Atlassian Forge Availability Issues

To deploy your app, we use the Atlassian Forge CLI. Sometimes Forge experiences temporary outages or service degradation that are outside of our control. In such cases, the deployment may fail due to Forge being unavailable.

How to fix it?

• Check the Atlassian Developer Status page: https://developer.status.atlassian.com/

• If Forge is experiencing an incident or degraded performance, wait for Atlassian to resolve the issue and try deploying again later.

Error Examples

There was a network connection issue while trying to contact the Atlassian API, which may be temporary. Ensure your internet connection is stable. No authorization or scope issues are indicated in the message.

How does it look?