wtfutil/wtf · error

authentication failed! Please log in to Spotify by visiting

Error message

authentication failed! Please log in to Spotify by visiting the following page in your browser: 

What it means

The spotifyweb widget requires an authenticated Spotify client and a player state before it can poll the API. If either the OAuth client (w.client) or the cached player state (w.playerState) is nil, the widget cannot talk to Spotify and returns this error, whose message includes the authURL so the user can complete the browser-based OAuth flow.

Source

Thrown at modules/spotifyweb/widget.go:135

	// This mostly likely has to do with the fact that the URL includes some very special characters that no terminal likes.
	// The only solution would be to include quotes in the command, which is why I do here, but it doesn't work.
	//
	// If inconvenient, I'll remove this option and save the URL in a file or some other method.
	utils.OpenFile(`"` + authURL + `"`)

	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 {

View on GitHub (pinned to bb838c1ccb)

Solutions

1. Open the URL printed in the error message in a browser and complete the Spotify OAuth login, then restart/refresh WTFUtil.
2. Verify the spotifyweb module settings: valid clientID and clientSecret (or secretKey) in the WTFUtil config.
3. Check that the token cache file for the module exists and is writable so the session persists across restarts.
4. Ensure the Spotify redirect URI configured in the Spotify developer dashboard matches the one WTFUtil uses.

Example fix

// before: widget shows error with auth URL, user never logs in
// after: complete the OAuth flow once so w.client is set
// 1. click/visit the authURL printed by the error
// 2. approve scopes in the browser
// 3. restart wtfutil; w.client != nil and refresh succeeds

if widget.client == nil {
    // complete the OAuth login at authURL before enabling refresh
    return
}

if err := widget.refreshSpotifyInfos(); err != nil {
    if strings.Contains(err.Error(), "authentication failed") {
        // prompt the user to visit the embedded authURL
    }
}

When it happens

Trigger: Widget.Refresh -> refreshSpotifyInfos() is called while w.client == nil or w.playerState == nil. This is the state before the user has ever completed the Spotify OAuth login, or after the token/session data was not loaded.

Common situations: First run of the spotifyweb module without logging in; deleted or missing OAuth token cache; Spotify app credentials (client ID/secret) misconfigured so authentication never completes; running WTFUtil headless where the browser login flow cannot be finished.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• panic(err)
• Couldn't get token
• extracting player state failed! Please refresh or restart WT
• errors.New(response.ErrorMessage)
• github client v3 failed to load

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