gitroomhq/postiz-app · error · RefreshToken

Refresh token error

Error message

Refresh token error

What it means

While polling a pending Mastodon post status, the Mastodon API answered 401, so the access token is no longer valid. Thrown as a RefreshToken error so the platform attempts token refresh/re-authentication. Note: Mastodon tokens are long-lived; a 401 usually means revoked or wrong-scoped token or app credentials changed.

Source

Thrown at libraries/nestjs-libraries/src/integrations/social/mastodon.provider.ts:319

          },
          // @ts-ignore - undici-only option; blocks SSRF to internal IPs
          dispatcher: getSsrfSafeDispatcher(),
        } as any);
      } catch (err) {
        // Transient status-check error: the media may finish processing just
        // fine, keep polling - if the instance stays broken the workflow
        // exhausts its checks and warns the user properly.
        return { status: 'pending', pendingData };
      }

      if (response.status === 206) {
        // consume the body so the undici socket is released between polls
        await response.text().catch(() => '');
        return { status: 'pending', pendingData };
      }

      if (response.status === 401) {
        throw new RefreshToken(
          this.identifier,
          await response.text().catch(() => '{}'),
          '{}'
        );
      }

      if (response.status === 404 || response.status === 410) {
        // The media GET only sees UNATTACHED media: after a finalize whose
        // outcome was lost, an already-published status makes its media 404
        // here. Never conclude "expired, post again" (that instruction is the
        // duplicate path) - keep checking the remaining media (a later 206
        // still wins) and let the idempotent finalize either dedupe into the
        // existing status or get Mastodon's verdict.
        await response.text().catch(() => '');
        continue;
      }

      if (response.status === 422) {

View on GitHub (pinned to 0f1647f749)

Solutions

1. Reconnect the Mastodon integration to obtain a fresh access token
2. Verify the token and instance URL match (token from mastodon.social used against another instance)
3. Confirm the app still exists and has read:statuses/write:media scopes

function isRefreshTokenError(e: unknown): e is RefreshToken {
  return e instanceof Error && (e as any).name === 'RefreshToken';
}

catch (e) { if (isRefreshTokenError(e)) await refreshTokenAndRetry(); }

When it happens

Trigger: GET of the scheduled status returns HTTP 401 — token revoked by user, app deauthorized, or instance changed client credentials.

Common situations: User revoked the app from Mastodon settings, instance admin revoked the app, token stored against a different instance, or clock/env issues sending stale auth header.

Related errors

• Organization not found
• Integration not allowed
• Integration not allowed
• This integration requires an external URL and is not support
• Failed to generate auth URL

AI-assisted analysis of gitroomhq/postiz-app@0f1647f749 (2026-08-27). Data as JSON: /api/errors/e3eaead7e11db4e0. Report an issue: GitHub.