Skip to main content

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.

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.