Linear Integration Troubleshooting

Quick Links

Linear Setup Guide

Return to the main Linear integration setup steps.

Integrations Overview

Browse all available integration guides.

Fast Checks

Confirm the workspace shows a connected Linear organization.
Confirm a default team is selected in Connection.
Confirm Sync enabled is on for the active connection.
Reconnect if OAuth permissions changed after initial setup.

OAuth and Connection Errors

OAuth failed or returned to dashboard with error

Start the connection flow again from the Linear integration page.
Complete OAuth in one browser tab to avoid invalid state errors.
Verify redirect URL uses the same app domain where you initiated the flow.

Organization conflict

If you see an organization conflict message, the same Linear org is already linked to a different Superfeedback workspace. Disconnect it there first.

Organization switch blocked

If the UI says switching org requires disconnect, disconnect the current Linear org first, then reconnect the new one.

Webhook Setup Errors

"Webhook setup requires Linear admin"

Your Linear account is not an org admin/owner. Reconnect with an account that can manage webhooks.

"Webhook setup requires OAuth admin scope"

Reconnect and grant the admin scope requested in OAuth. Without this scope, inbound updates from Linear cannot be configured.

Webhook setup failed without a specific code

Reconnect the integration.
Confirm your Linear workspace allows webhook creation.
If failure persists, capture details and contact support.

Status Mapping Issues

"Sync statuses from Linear" is disabled

Set a default team in the Connection section first. The status catalog sync depends on team context.

Statuses are not mapping as expected

Re-open Status mapping and verify direct mappings.
Verify both fallback columns are set for each status type.
Save mappings again after any change.

Backfill Issues

Backfill started but did not link expected tickets

Backfill only processes open tickets.
Review progress counters for skipped and failed.
Re-run backfill after fixing mapping/default configuration.

Backfill stalled

Use Stop, then run it again.
Verify Linear connection remains active.

Backfill skipped many records

Check whether skipped tickets are already linked.
Confirm only open tickets are expected in this run.
Re-run after fixing mappings and defaults.

When to Contact Support

Contact support with:

workspace slug
connection ID from Backfill and diagnostics
timestamp of last failure
screenshot of the visible error
whether issue affects OAuth, mapping, or backfill