> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postiz.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
Postiz. The OAuth handshake spans three parties — your browser, the social
provider, and the Postiz 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 Postiz.

**What it means:** Postiz 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; Postiz 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 Postiz tab in a single, fresh browser session.
2. Whitelist `platform.postiz.com` (or your self-hosted domain) in any
   privacy extensions for the duration of the connect.
3. Click "Add Channel" again from inside the Postiz app — never
   bookmark or refresh the provider's authorize page.
4. If your browser is in private/incognito mode, switch to a normal window.

**Self-hosters:** ensure `FRONTEND_URL` and `NEXT_PUBLIC_BACKEND_URL`
resolve cookies to the same parent domain. If frontend and backend live on
different domains (e.g. `app.example.com` and `api.example.com`), browsers
will treat the backend cookie as third-party and the state token may not
round-trip.

## "invalid\_grant"

The OAuth code Postiz 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 Postiz 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 Postiz 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:** the Postiz backend tried to talk to the provider's
API and the request failed at the network level — DNS, TLS, or a refused
connection.

**Common causes**

* Self-hosted Mastodon on a custom instance the Postiz backend can't
  reach (firewall, missing DNS).
* GMB metrics endpoint blocked by egress filtering.
* A reverse proxy in front of Postiz is rewriting the outbound request.

**Fix**

1. Verify the Postiz backend container can resolve and reach the
   provider's hostname (`curl https://provider.example.com/` from inside
   the container).
2. If you're behind a corporate egress proxy, set `HTTPS_PROXY` and
   `HTTP_PROXY` for the backend process.

## "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 — Postiz usually falls back successfully on the second
attempt.