Troubleshooting

Cuelight's messages say what happened and what to do. This page lists them all with the usual cause. Search it for the exact text you see.

The panel

The Next steps panel isn't on the work item. Look in the right column, below the other fields. In some Jira plans the panel starts collapsed; expand it once and Jira remembers. If it's still missing, check that the app is installed under Settings → Apps → Manage apps.

No actions for this work item. No action's showWhen matches this work item. Check the project key (case-sensitive), the issue type, status and labels. Admins see a Set up actions link under the message.

Couldn't load the next steps. Reload the page to try again. The panel couldn't read the work item's state. Reload. If it keeps happening, check Atlassian's status page for Forge incidents.

This next step has expired or was already used. Reload the panel. Someone else pressed a step from the same run, or the step passed its expiresInHours. Reload to see the current steps.

The action "x" isn't set up anymore. Reload the panel. An admin removed or renamed the action after the panel loaded. Reload.

Disabled buttons

Only members of Release Managers can run this. You're not in any of the action's allow.groups. Ask a Jira admin to add you to the group, or to change the action.

Another run of this action is in progress. The action uses concurrency: per-issue and a run is active. Wait for it to finish. A run that hasn't reported for 30 minutes stops blocking.

GitHub isn't connected yet. Ask a Jira admin to connect it in Cuelight settings. No GitHub token is saved. See GitHub setup.

Couldn't check your permissions. Try again. Jira didn't return your groups in time. Try again in a moment.

Cuelight's subscription isn't active. Ask a Jira admin to renew it under Settings → Apps → Manage apps. The Marketplace subscription ended or wasn't renewed, so every button is off. An admin renews it.

Starting an action

Couldn't start the action. Reload the page and try again. Something failed between the panel and Cuelight. Reload and press again.

GitHub token is invalid or expired. Ask a Jira admin to replace it. The token was revoked or reached its expiration date. An admin creates a new one and uses Replace token on the GitHub tab.

The GitHub token can't run workflows in acme/shop. It needs Actions: read and write. The token doesn't include the repository, or its Actions permission is read-only. Edit the token in GitHub.

GitHub rate limit reached. Try again in 3 minutes. The token's owner has used up GitHub's API quota. Wait the time shown.

Workflow deploy.yml wasn't found in acme/shop on main. The file name in github.workflow is wrong, the file isn't in .github/workflows/, or it isn't on the default branch. GitHub only starts workflow_dispatch workflows that exist on the default branch.

deploy.yml in acme/shop has no workflow_dispatch trigger, so Cuelight can't start it. Add "workflow_dispatch:" under "on:" in the workflow file. GitHub only starts workflows that list workflow_dispatch as a trigger. Add it on the default branch.

GitHub can't find the branch or tag "main" in acme/shop. Ask a Jira admin to check the branch for this project in Cuelight settings → Projects. The branch in the project mapping, or the one github.ref renders, doesn't exist in the repository. Fix the name or create the branch.

GitHub rejected the inputs: … Use Test on the Actions tab in Cuelight settings to list what the workflow is missing. The workflow doesn't declare an input the action sends, or a required input is empty. Use Test on the Actions tab to list what's missing.

GitHub returned an error (HTTP 500). Try again, and ask a Jira admin to check the Cuelight settings if it keeps happening. An unexpected response from GitHub, often a temporary outage. Try again.

Couldn't reach GitHub. Try again. A network problem between Atlassian and GitHub. Try again.

Project OTHER isn't mapped to a GitHub repository. Ask a Jira admin to map it in Cuelight settings → Projects. The action shows on work items outside the projects you mapped, because its showWhen doesn't limit projects, and it has no github.repo. Map the project, set github.repo or add showWhen.projects.

This action has no GitHub workflow. Ask a Jira admin to fix it. The action is missing github.workflow. An admin fixes the JSON.

This action has nothing to change. Ask a Jira admin to add labels or fields to it. A jira_update action has no addLabels, removeLabels or setFields.

The GitHub ref "…" came out empty for this work item. Ask a Jira admin to check github.ref. github.ref uses a template, like {{issue.fields.customfield_10042}}, that's empty on this work item.

… is a X field. Cuelight can only set text, number and single-select fields. jira.setFields points at a field type Cuelight can't write. Use a label or a different field.

The field customfield_10042 can't be edited on SHOP-142. Check that it's on the project's edit screen and the field id is right. Jira refused the change. Add the field to the project's edit screen, or fix the id in jira.setFields.

Story points needs a number, but the value was "…". A template in jira.setFields rendered text for a number field.

While a run is active

No report received The workflow hasn't reported in 30 minutes. Usually the report step is missing, it doesn't run when an earlier step fails (add if: always()), or the workflow doesn't pass the Cuelight inputs on. Press Check status to ask GitHub once.

No report received. GitHub says the run failed. The run finished on GitHub without reporting. Cuelight recorded GitHub's result. Add the report step so next time the work item gets a message and next steps.

GitHub says the run is still in progress. Nothing to fix; the run is still going.

Couldn't check the run. Try again in a moment. Cuelight couldn't reach GitHub to check. Try again.

GitHub couldn't find run 123456 in acme/shop. It may have been deleted. The run was deleted on GitHub, or the token lost access to the repository. Open the workflow on GitHub to see its runs.

GitHub didn't return a run id when this started, so Cuelight can't check it. Open deploy.yml in acme/shop on GitHub. GitHub started the run without telling Cuelight its id, so Check status can't look it up. Follow the run on GitHub; its report still reaches the work item.

Settings

GitHub says this token is invalid or expired. Create a new fine-grained token and paste it here. The token was revoked, expired or mistyped.

Paste the whole GitHub token. It starts with github_pat_ and has no spaces. The pasted value is empty or has spaces in it. Copy the token again from GitHub.

acme/shop wasn't found, or the GitHub token can't access it. Check the name and the token's repository access. Check the owner/repo spelling and add the repository to the token's repository access.

Missing inputs: cuelight_callback_url, cuelight_token. Declare them under on.workflow_dispatch.inputs so the workflow can report back, or set github.report to false. Shown by Test. Add the listed inputs to the workflow, as in GitHub setup.

GitHub will reject inputs the workflow doesn't declare: … Declare them in deploy.yml or remove them from github.inputs. Shown by Test. The action sends an input the workflow doesn't list under on.workflow_dispatch.inputs. Declare it or remove it from the action.

Cuelight can't tell which repository to check. Set github.repo, or add showWhen.projects with a mapped project. Shown by Test. The action has no github.repo and no showWhen.projects, and more than one project is mapped, so Cuelight doesn't know which repository to test against.

Someone else saved the actions after you opened this page. Copy your changes, reload, and apply them again. Two admins edited the actions at once. Cuelight kept the other save so nothing is lost silently.

Only Jira admins can change Cuelight settings. Settings need the Jira administrator permission.

Report API

Reports and offers return an error code with a message. The full table is in Report API. The ones people hit most:

CodeUsual causeFix
missing_tokenThe report step ran in a workflow Cuelight didn't startStart it from Jira, or send an offer with the install key
expired_tokenThe run took longer than 24 hours to reportReport sooner, or report running early and finish with Check status
invalid_install_keyThe key was regeneratedUpdate CUELIGHT_INSTALL_KEY wherever you use it
unknown_actionA typo in next, or the action was removedUse an id from the Actions tab
invalid_inputA next step's input isn't a field of that action's formMatch the names in the action's form
run_finalTwo final reports from one runSend only one final status
issue_not_foundWrong key, or Cuelight can't see the work itemCheck the key and the project's app access