Jira troubleshooting

Every Jira problem is anchored to one of two objects. The connection is the credential itself, added and removed from Dashboard → Integrations. The Jira source is the Workspace pointing at one of those connections, set under Workspace settings → Integrations & notifications, and shared by that Workspace's Planning and Retro Rooms.

Jira connections need the integrations entitlement, which is a paid-plan capability. It resolves through the organization you own — if you own no organization, SprintBee treats you as Free even when you are a member of a paid one, and the connection screens will be hidden or refuse you.

Connection failures#

SprintBee only makes a Jira call through a connection whose status is Connected. Anything else, and the call is refused before it leaves the server.

Personal OAuth connections#

Jira connection needs to be reconnected#

The stored access and refresh tokens are gone, expired, or revoked — commonly because someone disconnected SprintBee from the Atlassian side, or the connection row is no longer connected. SprintBee has already flipped the connection to Reconnect in Dashboard → Integrations. Reconnect it there, signing in with the Atlassian account that should own it.

Atlassian rotates refresh tokens on every refresh, so two SprintBee servers can briefly race for the same one. SprintBee detects that case and reuses the winner's token rather than breaking a healthy connection, so a single transient failure is not a reason to reconnect.

Jira is temporarily unavailable. Try again in a moment.#

A network fault or an Atlassian 5xx while refreshing the token. Deliberately not treated as a dead connection — nothing is marked for reconnection and the stored credentials are still good. Retry.

No Jira sites are listed#

The Atlassian account that authorized SprintBee cannot reach a Jira Cloud site, or its site access changed after the connection was made. Reconnect from Dashboard → Integrations using an account with access to the intended site.

App connections#

The Jira app credential is refreshing. Try again shortly.#

Forge issues SprintBee a short-lived app credential, renewed by install and upgrade events plus an hourly trigger. This message means the stored one has aged out and the next trigger has not landed. Wait and retry. SprintBee never falls back to a person's OAuth identity to cover the gap.

That pairing code is invalid or expired#

Pairing codes are eight characters and live for 15 minutes. Creating a new code for an organization also expires any unused code it already had, so an older code in someone's clipboard will fail. Generate a fresh one and paste it straight away.

This Forge installation has not checked in yet#

The app is installed in Jira but has not yet reported itself to SprintBee, so there is nothing to pair the code to. This resolves on its own once the installation event is processed.

This Jira site is already paired to another organization#

A Forge installation belongs to exactly one SprintBee organization. Re-pairing the same organization is fine and simply re-authorizes. Moving a site to a different organization means unpairing it first.

Only the organization owner can pair a Jira app#

Pairing codes are created by the organization owner and nobody else — not admins, not members.

Search and import failures#

Nothing to search#

Configure a Jira source in room settings before importing issues#

The Add work items panel found no Jira source for this room. Despite the wording, the place to fix it is Workspace settings → Integrations & notifications: choose the Jira site and connection there, and save.

A participant has no search box#

Inline Jira search is a moderator surface. Participants paste issue keys or URLs into the Jira tab to raise an import request, which a moderator approves or dismisses from the queue.

Refused or incomplete results#

Jira rejected this connection. Reconnect Jira and try again.#

Jira answered a read with 401 or 403. For a personal connection, reconnect it. For an app connection, confirm the app is still installed on that Jira site and still paired to your organization. This is Jira's own verdict on the credential, so nothing in SprintBee's settings will change it.

Searches return fewer issues than expected#

Project scope is applied to every search — presets, keyword lookups and raw JQL alike — as an added project in (...) clause. Check the Jira source's Project scope list; an empty list means every project on the site is searchable. Results are also bounded by what the connected identity can see: a personal connection sees what its Atlassian account sees, an app connection sees what the installed app is granted.

Write-back failures#

Write-back fires once, automatically, when a moderator accepts an estimate for a round linked to a connected Jira issue. Each attempt records succeeded, failed or skipped against the round, so the last outcome is always inspectable.

Jira refused the write#

Jira rejected the update. Reconnect Jira to grant write access, then try again.#

Jira answered the field update with 401 or 403. On a personal connection this almost always means it does not hold write:jira-work — usually because it predates write-back. Reconnect it to consent to the current scope list. Read and import keep working in the meantime; only writes are blocked.

Jira rejected the update: …#

Everything after the colon is Jira's own validation text, passed through verbatim. The two usual causes are a mapped field that will not accept the value's type, and the connected identity lacking edit permission on that field in the target project.

The write never happened#

Recorded reason	What triggered it
No estimate to write to Jira.	The accepted card produced no writable value — blank, or a non-estimate card (see below).
No accepted estimate is compatible with the mapped Jira field(s).	Every mapped field rejected the value's type, or the field id is no longer returned by Jira.
(nothing recorded)	Write-back is off for this Workspace, no field is mapped, or the item is not a connected Jira item.

Non-estimate cards are never written#

?, ☕ and ∞ mean "no estimate" and are dropped before any field is touched. Pass is not in that set — it is a real string and will be written to a text or single-select field.

Numeric fields silently drop non-numeric values#

Mapped fields may be numeric, plain text or single-select. A T-shirt size written at a numeric field is skipped rather than erroring, so a deck that does not match its target field looks like silence. Map non-numeric decks to a text or single-select field.

Split Dev/QA totals need two numbers#

The Dev + QA total field is only written when both the Dev and QA estimates parse as numbers. The individual Dev and QA fields are unaffected.

The item is a linked issue, not a connected one#

An issue captured by the Browser Companion or pasted as a bare key is a linked source: an issue key and a best-effort title with no API access behind it. Write-back, refresh and enrichment all require a connected source imported through the Jira connection.

Sync and sprint failures#

Refresh queue items automatically is greyed out#

The connection lacks manage:jira-webhook, so SprintBee cannot subscribe to Jira updates. Reconnect Jira from Dashboard → Integrations to grant it. Project scope is not a prerequisite — an unscoped source subscribes across every project.

The Retro sprint picker offers nothing#

Every one of these degrades rather than blocking: the Retro Period stays editable by hand throughout.

Notice	Cause
The Jira connection needs reconnecting.	Access expired, or the connection predates the granular sprint scopes. Reconnecting grants them; everything else already works.
The Jira boards in scope are Kanban boards.	Kanban boards have no sprints. Scope the source at a project with a Scrum board.
No Jira board is in scope for this Workspace.	Add the projects this team works in to the Workspace's Jira source.
Jira has no sprints or cycles yet.	Nothing to list. Create one in Jira.
Only the Retro's active facilitator can list sprints.	Not a Jira fault — take over facilitation.

Unsupported setups#

Setup	Status
Jira Cloud (commercial)	Supported by personal OAuth and the app connection
Jira Data Center / Server	Not supported — both connections target Atlassian's cloud API
Atlassian Isolated Cloud	Not supported
More than one Jira source per Workspace	One active source at a time, shared by Planning and Retro
One Forge installation, several organizations	One installation pairs to exactly one organization