extracting player state failed! Please refresh or restart WT

Error message

extracting player state failed! Please refresh or restart WTF

What it means

After authentication succeeds, refreshSpotifyInfos calls w.client.PlayerState() to fetch current playback. If that API call fails (network problem, expired/revoked token, Spotify outage), the widget wraps the failure in this error and advises refreshing or restarting WTF, since the underlying client state may be stale.

Source

Thrown at modules/spotifyweb/widget.go:140

	widget.settings.RefreshInterval = 5 * time.Second

	widget.initializeKeyboardControls()

	widget.View.SetWrap(true)
	widget.View.SetWordWrap(true)

	return &widget
}

func (w *Widget) refreshSpotifyInfos() error {
	if w.client == nil || w.playerState == nil {
		return errors.New("authentication failed! Please log in to Spotify by visiting the following page in your browser: " + authURL)
	}
	var err error
	w.playerState, err = w.client.PlayerState()
	if err != nil {
		return errors.New("extracting player state failed! Please refresh or restart WTF")
	}
	w.Album = fmt.Sprint(w.playerState.Item.Album.Name)
	artists := ""
	for _, artist := range w.playerState.Item.Artists {
		artists += artist.Name + ", "
	}
	artists = artists[:len(artists)-2]
	w.Artists = artists
	w.Title = fmt.Sprint(w.playerState.Item.Name)
	w.TrackNumber = w.playerState.Item.TrackNumber
	if w.playerState.Playing {
		w.Status = "Playing"
	} else {
		w.Status = "Paused"
	}
	return nil
}

View on GitHub (pinned to bb838c1ccb)

Solutions

Restart WTFUtil so the spotifyweb client re-authenticates and gets a fresh token.
If it persists, redo the browser OAuth login to obtain a new refresh token.
Check network connectivity to api.spotify.com and any proxy/firewall interference.
Verify system clock is correct — significant skew breaks OAuth token validation.

Example fix

// before: stale token causes PlayerState() to fail every refresh
// after: force a clean re-auth
$ rm -f ~/.config/wtf/spotifyweb_token.json  # module token cache
$ wtfutil  # complete the OAuth login again when prompted

Defensive patterns

Strategy: retry

Validate before calling

if widget.client == nil {
    return // re-authenticate first; PlayerState will fail anyway
}

Try / catch

if err := widget.refreshSpotifyInfos(); err != nil {
    if strings.Contains(err.Error(), "extracting player state failed") {
        // back off, then restart the client or full app to re-auth
        time.Sleep(30 * time.Second)
    }
}

Prevention

Restart WTFUtil periodically for long-lived sessions with Spotify modules.
Keep the system clock synchronized (OAuth tolerates little skew).
Re-login when you change your Spotify password (revokes tokens).

When it happens

Trigger: w.client.PlayerState() returns a non-nil err during refresh — e.g. the access token expired and refresh failed, the network dropped mid-poll, or Spotify's API returned an error.

Common situations: Long-running WTFUtil session where the Spotify refresh token expired or was revoked (user changed password / logged out all devices); laptop waking from sleep with a dead connection; Spotify API outage or rate limiting.

Related errors

AI-assisted analysis of wtfutil/wtf@bb838c1ccb (2026-09-03). Data as JSON: /api/errors/fb8aa446e3aa3724. Report an issue: GitHub.