Provider connection errors

Before reconnecting a provider

Use this page when a provider connection blocks ticket export, status sync, repository remediation, webhook delivery or platform access. Start from the saved connection because it owns deployment mode, base URL, auth status, scopes, revoke state and retry timing.

• Reconnect the provider
• Check `provider_error_code`, `base_url`, `deployment_mode`, `auth_status` and scope fields.
• Keep tokens, OAuth secrets, private keys and webhook secrets inside the product connection flow.

Triage the provider target

Follow the path `Settings → Provider connection → Error reason → Reconnect, revoke, retry or stop`.

1. Open `/settings` and choose the failing provider connection. Result: `provider_connection_id`, `provider_key`, `deployment_mode`, `base_url` and `auth_status` are visible before retrying exports, sync or remediation.
2. Read `provider_error_code`, `required_scopes`, `granted_scopes`, `token_expires_at` and `last_successful_sync_at`. Result: the page separates revoked auth, missing scope, unreachable base URL and rate-limit states.
3. If `PROVIDER_BASE_URL_UNREACHABLE` or `PROVIDER_BASE_URL_BLOCKED` appears, verify the URL belongs to the customer and matches cloud or self-hosted deployment. Result: unsafe or private-network targets stay blocked until connectivity is configured.
4. If `PROVIDER_AUTH_FAILED` or `PROVIDER_TOKEN_REVOKED` appears, reconnect through the provider button in `/settings`. Result: tokens are replaced through the product flow without exposing secrets.
5. If `PROVIDER_PERMISSION_MISSING` or `PROVIDER_SCOPE_MISSING` appears, compare `required_scopes` with `granted_scopes`. Result: the customer adds only the scopes needed for the selected export, issue sync or repository workflow.
6. If `PROVIDER_RATE_LIMITED` appears, wait for `retry_after` before another export, sync or connection test. Result: retry pressure does not create duplicate provider failures.
7. For self-hosted providers, check `allowlist_status`, tunnel status and base URL safety before retrying. Result: `PROVIDER_SELF_HOSTED_CONNECTIVITY_BLOCKED` routes to self-hosted connectivity instead of token changes.
8. Use revoke only when the connection is wrong, stale or unsafe, then confirm `revoke_status`. Result: old credentials stop working before a new target is saved.
9. Return to `/reports/{report}/ticket-exports`, `/fix-tasks/{fixTask}` or the original workflow after the provider status is ready. Result: the owning workflow can retry with the recovered provider.
10. Continue to Cloud and self-hosted integrations, the specific provider setup guide, Ticket export failures or Self-hosted connectivity when the provider target remains blocked. Result: the next guide owns the remaining setup or delivery problem.

Provider error reasons

Use the reason code before reconnecting or revoking.

• `PROVIDER_AUTH_FAILED` and `PROVIDER_TOKEN_REVOKED` mean the saved auth cannot be used anymore.
• `PROVIDER_PERMISSION_MISSING` and `PROVIDER_SCOPE_MISSING` mean the provider is reachable but lacks the required permission for the selected workflow.
• `PROVIDER_BASE_URL_UNREACHABLE` and `PROVIDER_BASE_URL_BLOCKED` mean the target host, scheme, path or private-network status is unsafe or unavailable.
• `PROVIDER_RATE_LIMITED` means wait for `retry_after` instead of retrying repeatedly.
• `PROVIDER_SELF_HOSTED_CONNECTIVITY_BLOCKED` means network reachability must be fixed before auth changes matter.

Reconnect revoke or retry rules

Use the product action that matches the reason.

• Reconnect only through `/settings`, OAuth, app install or the provider-specific setup flow.
• Revoke when the connection belongs to the wrong workspace, outdated host, stale app installation or unsafe target.
• Retry exports, sync or remediation only after `auth_status`, `required_scopes`, `granted_scopes`, `base_url` and `deployment_mode` are ready.
• Keep secrets out of ticket exports, provider notes, docs and support comments.

Ready and blocked provider states

A provider is ready when the saved connection matches the workflow that needs it.

• Ready: provider key is correct, base URL is safe, deployment mode matches, auth is active, required scopes are granted, revoke is not pending and rate-limit cooldown has passed.
• Still blocked: revoked token, missing scope, unreachable base URL, unsafe self-hosted target, private-network allowlist missing, rate limit active, wrong workspace or unsupported provider mode.
• Stop: the provider cannot support the requested workflow, the target is not customer-owned or the private-network path is not approved.

Continue after provider recovery

Use the linked guide for the setup or delivery problem that remains.

• Cloud and self-hosted integrations explains deployment mode, auth method, base URL and allowlist setup.
• Self-hosted connectivity explains private-network, tunnel and allowlist blocks.
• Ticket export failures explains delivery attempts after the provider connection is ready.
• GitHub cloud and enterprise, Jira cloud and data center and Generic webhook automation explain provider-specific setup paths.
• Resolve blocked or failed states explains how to return to the workflow that first showed the provider block.