Troubleshooting

"API token not found"

ReleaseJet checks six sources, in order: RELEASEJET_TOKEN → provider env (GITLAB_API_TOKEN / GITHUB_TOKEN) → per-repo entry in ~/.releasejet/credentials.yml → host entry → legacy provider-type entry → bare-text ~/.releasejet/credentials. The error lists every key it tried for your host.

releasejet auth set-token --host gitlab.com
# or set an env var:
export RELEASEJET_TOKEN=<your-token>

See Authentication & tokens for the full lookup, including per-repo overrides.

Wrong token resolved

ReleaseJet picked up a token, but the wrong one — for example, a legacy gitlab: key fired before the host entry you expected. Run releasejet auth show-token to see every step of the resolution chain and which one matched:

releasejet auth show-token                          # auto-detect from current repo
releasejet auth show-token gitlab.com/myorg/api     # explicit

See Managing tokens for the full diagnostic output.

"Tag not found in remote repository"

The tag exists locally but hasn't been pushed:

git push origin <tag>

"Invalid tag format"

Tags must match v<semver> (e.g., v1.2.0) or <prefix>-v<semver> (e.g., mobile-v1.2.0). Suffixes like v1.2.0-beta are supported but the core version must be valid semver. See Tag formats.

"Tag is lightweight" warning in `generate` output

ReleaseJet couldn't determine the exact time the tag was created. Lightweight tags (plain git tag without -a) fall back to the commit date, which may include issues closed after the commit but before the tag was pushed.

Fix by upgrading to an annotated tag:

git tag -a v1.0.0 -m "Release v1.0.0" --force
git push origin v1.0.0 --force

Or let ReleaseJet create a release object on your provider — it'll have the correct timestamp:

releasejet generate --tag v1.0.0 --publish

Issues missing from release notes

ReleaseJet includes issues closed between the previous tag and the current tag, filtered by closedAt. Check:

The issue is closed (not just merged for PRs).
The close date falls within the tag window.
The issue has the correct client label (multi-client repos).

Run with --debug to see the date range and which issues were filtered.

"Request failed with status 401 / 403"

Token scope mismatch. GitLab needs api; GitHub needs repo. See Token scopes.

`source: pull_requests` not working

PR source is GitHub-only. GitLab projects must use source: issues (the default).

Config changes not taking effect

Run with --debug to see the loaded config:

releasejet generate --tag <tag> --debug

Invalid values (e.g., uncategorized: strictt) produce clear error messages rather than being silently ignored.

"Orphan tag detected" on `generate`

You changed tagFormat and older tags no longer match. ReleaseJet shows the most recent orphan tag and suggests --since <tag> or re-tagging. See Tag formats — migrating.

Still stuck?

Open an issue: github.com/makisp/releasejet/issues with the output of releasejet <command> --debug.

Troubleshooting

On this page