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:
| Code | Usual cause | Fix |
|---|---|---|
missing_token | The report step ran in a workflow Cuelight didn't start | Start it from Jira, or send an offer with the install key |
expired_token | The run took longer than 24 hours to report | Report sooner, or report running early and finish with Check status |
invalid_install_key | The key was regenerated | Update CUELIGHT_INSTALL_KEY wherever you use it |
unknown_action | A typo in next, or the action was removed | Use an id from the Actions tab |
invalid_input | A next step's input isn't a field of that action's form | Match the names in the action's form |
run_final | Two final reports from one run | Send only one final status |
issue_not_found | Wrong key, or Cuelight can't see the work item | Check the key and the project's app access |