> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groniz.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OAuth & Channel Connect Errors

> Invalid state, invalid_grant, and fetch failed during the connect flow

Connecting a social channel is the highest-volume source of user errors on
Groniz. The OAuth handshake spans three parties — your browser, the social
provider, and the Groniz backend — and any one of them can break the flow.

## "Invalid state"

By far the most common error. You see it as a flash-message after the
provider redirects back to Groniz.

**What it means:** Groniz generates a one-time CSRF token (the `state`
parameter) when you start the connect flow and stores it against your
session. The provider returns it in the redirect; Groniz compares the two.
A mismatch — or a missing token — produces this error.

**Common causes**

* You started the connect in one browser tab and finished it in another.
* You refreshed the provider's login page mid-flow.
* A third-party-cookie blocker (Brave's Shields, Safari's ITP, hardened
  uBlock, Firefox Total Cookie Protection) dropped the session cookie
  between the redirect out and the redirect back.
* You took longer than the session expiry to complete the OAuth login.

**Fix**

1. Open the Groniz tab in a single, fresh browser session.
2. Whitelist `groniz.com` in any privacy extensions for the duration
   of the connect.
3. Click "Add Channel" again from inside the Groniz app — never
   bookmark or refresh the provider's authorize page.
4. If your browser is in private/incognito mode, switch to a normal window.

## "invalid\_grant"

The OAuth code Groniz received from the provider was rejected when it
tried to exchange it for an access token.

**Common causes**

* The same OAuth code was used twice — usually from a double-click or
  retry after a transient error.
* The code expired (most providers give you \~60 seconds).
* The redirect URI configured on the provider doesn't exactly match the
  one Groniz is sending. A trailing slash counts.

**Fix**

1. Start the connect flow over from scratch — codes can't be reused.
2. Re-check the redirect URI in your provider's developer console
   matches the URL Groniz is redirecting to, character for character.

## "Failed to fetch" / "fetch failed" on provider connect

You see this on calls like `POST /integrations/provider/:id/connect`.

**What it means:** Groniz tried to talk to the provider's API and the
request failed at the network level — DNS, TLS, or a refused connection.

**Common causes**

* A custom/obscure Mastodon instance that isn't publicly reachable.
* A transient provider-side outage.

**Fix**

1. For Mastodon, double-check the instance URL is correct and the server
   is publicly reachable over HTTPS.
2. Wait a minute and retry the connect. If it keeps failing, email us at
   [hello@groniz.com](mailto:hello@groniz.com).

## "Unsupported file type" during connect

Some providers (TikTok, Instagram) try to upload a profile avatar as part
of channel attach. If the upstream image is in an exotic format, this
fails. Retry — Groniz usually falls back successfully on the second
attempt.