Skip to main content
Connecting a channel is the highest-volume source of errors here. The handshake spans three parties, so any one of them can break it.

​
Invalid state

The most common one, shown as a flash message after the provider redirects back.
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.
  • 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
1

Use one fresh browser session

Not a private window, and not two tabs.
2

Whitelist the domain in any privacy extension

app.postqueen.ai, or your own domain, for the length of the connect.
3

Start again from Add Channel inside the app

Never bookmark or refresh the provider’s authorize page.
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.

​
invalid_grant

The code the provider returned was rejected when PostQueen exchanged it for a token.
  • 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
1

Start the connect over

Codes cannot be reused.
2

Compare the redirect URI exactly

Provider console against what PostQueen redirects to. Each provider page lists the exact string.

​
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.
  • 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
1

Test reachability from inside the container

2

Check your egress path

See the warning below before you reach for a proxy.
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.

​
Unsupported file type during connect

TikTok and Instagram upload a profile avatar as part of attaching the channel, and an exotic source format fails.
Retry. The second attempt usually succeeds.