> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postqueen.ai/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 channel is the highest-volume source of errors here. The handshake spans three
parties, so any one of them can break it.

| You saw                        | Jump to                                                    |
| ------------------------------ | ---------------------------------------------------------- |
| **Invalid state**              | [below](#invalid-state)                                    |
| **invalid\_grant**             | [below](#invalid-grant)                                    |
| **Failed to fetch** on connect | [below](#failed-to-fetch-fetch-failed-on-provider-connect) |
| **Unsupported file type**      | [below](#unsupported-file-type-during-connect)             |

## Invalid state

The most common one, shown as a flash message after the provider redirects back.

<Info>
  PostQueen generates a one-time CSRF token when you start the connect and stores it against your
  session. The provider returns it in the redirect and the two are compared. A mismatch, or a missing
  token, produces this.
</Info>

<AccordionGroup>
  <Accordion title="What causes it" icon="circle-question">
    * You started the connect in one tab and finished it in another
    * You refreshed the provider's login page mid-flow
    * A third-party-cookie blocker dropped the session cookie between the redirect out and back: Brave Shields, Safari ITP, hardened uBlock, Firefox Total Cookie Protection
    * You took longer than the session expiry to finish the login
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="Use one fresh browser session">
    Not a private window, and not two tabs.
  </Step>

  <Step title="Whitelist the domain in any privacy extension">
    `app.postqueen.ai`, or your own domain, for the length of the connect.
  </Step>

  <Step title="Start again from Add Channel inside the app">
    Never bookmark or refresh the provider's authorize page.
  </Step>
</Steps>

<Warning>
  **Self-hosting?** `FRONTEND_URL` and `NEXT_PUBLIC_BACKEND_URL` must resolve cookies to the same
  parent domain. Split them across `app.example.com` and `api.example.com` and the browser treats the
  backend cookie as third-party, so the state token may never round-trip.
</Warning>

## invalid\_grant

The code the provider returned was rejected when PostQueen exchanged it for a token.

<AccordionGroup>
  <Accordion title="What causes it" icon="circle-question">
    * The same code was used twice, usually a double-click or a retry
    * The code expired. Most providers give you about 60 seconds
    * The redirect URI on the provider does not match the one PostQueen sends, character for character. A trailing slash counts
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="Start the connect over">
    Codes cannot be reused.
  </Step>

  <Step title="Compare the redirect URI exactly">
    Provider console against what PostQueen redirects to. Each provider page lists the exact string.
  </Step>
</Steps>

## Failed to fetch / fetch failed on provider connect

Seen on calls like `POST /integrations/provider/:id/connect`. The backend tried to reach the
provider's API and failed at the network level: DNS, TLS, or a refused connection.

<AccordionGroup>
  <Accordion title="What causes it" icon="circle-question">
    * A self-hosted Mastodon instance the backend cannot reach, through firewall or missing DNS
    * The GMB metrics endpoint blocked by egress filtering
    * A reverse proxy in front of PostQueen rewriting the outbound request
  </Accordion>
</AccordionGroup>

<Steps>
  <Step title="Test reachability from inside the container">
    ```bash theme={"system"}
    curl https://provider.example.com/
    ```
  </Step>

  <Step title="Check your egress path">
    See the warning below before you reach for a proxy.
  </Step>
</Steps>

<Warning>
  **PostQueen cannot use a corporate egress proxy.** `HTTPS_PROXY` and `HTTP_PROXY` are not read, and
  provider calls go out through a dispatcher that would ignore them anyway. You need a transparent
  proxy or an allowlist at the network layer.
</Warning>

## Unsupported file type during connect

TikTok and Instagram upload a profile avatar as part of attaching the channel, and an exotic source
format fails.

<Check>
  Retry. The second attempt usually succeeds.
</Check>