SpotifyPlus Integration

thlucas · May 5, 2026, 9:54pm

Yes, please open a new github Repository Issue Request for the ReadTimeoutError issue.

Thanks

shortybig · May 11, 2026, 3:15am

Hey @thlucas and @cedrict, I've spent many hours reading through all the documentation I can find and using ChatGPT, but I'm still unable to solve what appears to be the same issue cedrict was having.

I was able to successfully link my Premium account to SpotifyPlus but I can't figure out how to play music from my Chromecast Google speakers (a couple minis and a Google Home). I created the spotifyplus_tokens.json and it's inside the /homeassistant/.storage/ directory, yet I get the exact same token error cedrict posted about. I also confirmed the user profile matches what you two posted screenshots of and the test script has entity_id: media_player.spotifyplus_jason.

Best I could find is ChatGPT thinks I need to additionally include another item in the token file containing the sp_dc key pair, which I tried, but that also didn't work. What was your solution??

I'm using a raspberry pi 4B with core-2026.5.1, if that matters! Thank you!

thlucas · May 11, 2026, 2:58pm

@shortybig
@cedrict found that his issue was that the spotifyplus_tokens.json was placed in the wrong directory; he accidentally created a directory with a space in it, and placed the tokens file there. This caused the integration to not find the tokens file.
For example:

/config/ .storage/    <- incorrect directory name, starts with a space
/config/.storage/     <- correct directory name, starts with a dot (hidden name in some OS's)

If you are using the Home Assistant File Editor add-on, ensure that you have the "View hidden files" option turned on, so that you can see the .storage directory.

Possible Causes

the encoding of the spotifyplus_tokens.json file. What editor did you use to create the file? It should be saved as a UTF-8 encoded, plain-text format, with Unix (LF). I just use Windows notepad to create mine.
there could be more than one spotifyplus_tokens.json files in the config location. I would do a search of the entire \config (and sub-directories) for the spotifyplus_tokens.json filename. If multiple entries exist, then you should only keep the one in the /config/.storage/ directory.
are you sure your SMB share name is mapped to the correct location / machine? if you run multiple HA instances, then you may be editing a spotifyplus_tokens.json on a different machine or in a different directory. You might also try editing the file using the Home Assistant File Editor add-on. Check out this link for more information. Also be sure to enable access to the .storage hidden directory location in the config folder. This will allow you to edit the file directly within HA, and from the \config\ location the instance is using.

shortybig · May 12, 2026, 10:46pm

I used your AuthTokenGenerator.py script via Command Prompt and simply uploaded the resulting json directly to /homeassistant/.storage/
Confirmed via find / -name "spotifyplus_tokens.json" from the home directory in Terminal there is only one spotifyplus_tokens.json file and it's in /homeassistant/.storage/
I've only got the one HA instance! I can see the file in File Editor and it seems fine.

I just tried replacing the spotifyplus_tokens.json file with a .txt file (deleted the original and uploaded the text version), but it gave the same error. Below is the text file I used:

{
    "SpotifyWebApiAuthCodePkce/65b708073fc0480ea92a077233ca87bd/Shared": {
        "access_token": "REDACTED",
        "expires_at": 1778385487,
        "expires_in": 3600,
        "refresh_token": "REDACTED",
        "scope": [
            "streaming"
        ],
        "title": "Spotify Desktop App Client (REDACTED)",
        "token_type": "Bearer",
        "username": "REDACTED"
    }
}

thlucas · May 12, 2026, 11:29pm

@shortybig
Can you provide a screen capture (or list) of what other files you have in the /homeassistant/.storage/ location? I take it you don't have a /config/.storage/ location, as specified in the How to find the HA configuration directory instructions for how to locate the Home Assistant configuration directory.

If you are using Home Assistant Core installation type (config directory passed to the hass command), then shouldn't that be ~/.homeassistant/.storage/?

What is your Home Assistant installation type?

shortybig · May 12, 2026, 11:40pm

Sure! And it's weird, File Editor only shows /homeassistant/ but Terminal shows /homeassistant/ and /config/. But they're linked to each other. Deleting the original json from config also deleted it automatically from homeassistant. Likewise, uploading the new .txt to homeassistant, it shows up in config.

thlucas · May 13, 2026, 12:43am

@shortybig
It appears that homeassistant is an alias for config.

Note that the spotifyplus_tokens.txt needs to be renamed to spotifyplus_tokens.json in your example directory structure above. That is the correct .storage/ directory location.

Did you say that did not work with the .json extension?

If not, can you post a screenshot of the error that you receive?
Can you also post the script that you are executing to transfer playback?

Thanks - this is progress.

shortybig · May 13, 2026, 1:46am

ah, okay, and yeah I originally had spotifyplus_tokens.json. Here's the action:

action: spotifyplus.player_media_play_context
metadata: {}
data:
  entity_id: media_player.spotifyplus_jason
  context_uri: spotify:playlist:7ku6P1WcrImYYJ6Tv8tmKJ
  device_id: Bedroom speaker

The resulting error (same with .txt and .json):

Spotify Cast Application could not be activated on Chromecast device "8ed23e57572077f6f5c112b63c0b6279": Spotify Desktop Player authorization token was not found in the token cache file.

I also tried with quotations around the device id and confirmed the wrong device id returns: "Spotify Player device "test" was not found in the Spotify Connect device list; verify the device is discoverable via Zeroconf on the local network."

And no worries! I appreciate all the work you've done and your willingness to help users like me!

thlucas · May 14, 2026, 1:41am

@shortybig
Ok, I think I see the problem.

It appears that the AuthTokenGenerator process did not replace the Shared value in the token key with your Spotify LoginID value (in the spotifyplus_tokens.json file).

Change the following line in your /config/.storage/spotifyplus_tokens.json file from this:

SpotifyWebApiAuthCodePkce/65b708073fc0480ea92a077233ca87bd/Shared

to this, where YOUR_SPOTIFY_LOGINID is your Spotify LoginID value. The LoginId value can easily be found using the Spotify Developer Web portal, using the Get Current Users profile service. Click on the Try It button, then find the id response value.

SpotifyWebApiAuthCodePkce/65b708073fc0480ea92a077233ca87bd/YOUR_SPOTIFY_LOGINID

Note that you are just changing the Shared value to your Spotify LoginID value (this first 2 nodes of the token key are the same).

Hopefully that makes sense.

shortybig · May 14, 2026, 3:55am

It didn't work at first, with it returning the error of it taking it too long, but then I restarted HA and now it's working! Thank you so much for all your help!!

bdubsw · June 16, 2026, 10:50pm

With Sonos, if I play a song in a playlist or album, it loads all the tracks into the local queue, then plays. This causes a lag and prevents instant playback.

Is there a better way to play music on a Sonos in a context of a playlist or album?

thlucas · June 16, 2026, 11:57pm

@bdubsw
There is already code in the SpotifyWebApiProject library, SpotifyClient.PlayerMediaPlayContext method to handle this scenario. It first clears the Sonos local queue, then starts adding the items to play one by one. It checks for the first item added, then issues a SoCo play_from_queue command to start play of the queue, then continues to load the remaining items.

                # clear the Sonos local queue.
                _logsi.LogVerbose("Issuing command to Sonos device \"%s\": CLEAR_QUEUE" % (scDevice.Name))
                sonosPlayer.clear_queue()

                # add all context items to the Sonos local queue.
                sharelink = ShareLinkPlugin(sonosPlayer)
                for idx in range(0, len(arrUris)):

                    # add context to the Sonos local queue.
                    uri = arrUris[idx].strip()
                    _logsi.LogVerbose("Issuing command to Sonos device \"%s\": ADD_SHARE_LINK_TO_QUEUE (uri=%s)" % (scDevice.Name, uri))
                    sharelink.add_share_link_to_queue(uri)

                    # if this is the first item added, then start play of the queue as
                    # it may take awhile to load the rest of the items.
                    if (idx == 0):

                        # start playing the Sonos local queue.
                        _logsi.LogVerbose("Issuing command to Sonos device \"%s\": PLAY_FROM_QUEUE (index=%s)" % (scDevice.Name, offsetPosition))
                        sonosPlayer.play_from_queue(index=offsetPosition)
                
                        # was a track seek position specified?
                        if (positionMS > 0):

                            # seek to the position in the track.
                            sonosPosition:str = mediaPositionHMS_fromSeconds(positionMS / 1000)  # convert from milliseconds to Sonos H:MM:SS format
                            _logsi.LogVerbose("Issuing command to Sonos device \"%s\": SEEK (position=%s)" % (scDevice.Name, sonosPosition))
                            sonosPlayer.seek(position=sonosPosition)
                
                            # give Sonos Controller time to process the change.
                            if delay > 0:
                                _logsi.LogVerbose(TRACE_MSG_DELAY_DEVICE_SONOS % delay)
                                time.sleep(delay)

Do you have shuffle turned on by chance? This might affect play, as the Sonos device has to shuffle the local queue, but I am not sure on that.

Can you provide example YAML of the service call?

thlucas · June 18, 2026, 6:45pm

Well folks, it looks like Spotify Developers are forcing yet another change on us regarding the Spotify Web API which is used by the SpotifyPlus integration. It will be implemented immediately for new users, and on July 20, 2026 for existing token holders.

This change will be an inconvenience to Home Assistant users of SpotifyPlus (as well as HA Spotify), as it relies on automatic token refresh at specified 6 month intervals. This change will force the user to re-authenticate every 6 months, upon which they will forget WHY this is happening as well as HOW to refresh the token. That means more questions will be directed at ME (the author of the HA SpotifyPlus integration) to walk them through it. From MY perspective, it's a maintenance nightmare, as there will be continuous questions / complaints / support for Spotify changes!

anyway, more info on the change from the Spotify Developer Forum blog ...

What's changing

Refresh tokens will expire 6 months from when the user originally authorized your app
An expired token will return invalid_grant from the token endpoint
Refreshing an access token does not reset the 6-month clock
This only affects Authorization Code and PKCE flows, not Client Credentials

Timeline

New apps: effective now
Existing apps: effective from July 20th, 2026

You can leave your feedback on the Spotify Developer Refresh Token Expiration Discussion forum if you would like to make your voice heard regarding these changes.

thlucas · June 22, 2026, 7:45pm

FYI - just released a new version of the SpotifyPlus integration.

Be sure to check out the SpotifyPlus Card Dashboard as well.

This should gracefully handle the invalid_grant errors that will be generated due to the new Spotify Web API requirements (more info on the Spotify Developer Forum blog).

[ 1.0.202 ] - 2026/06/22

Added support for new Spotify OAuth refresh token limitations. The new logic will check for Spotify refresh token invalid_grant errors, as Spotify will deactivate refresh tokens after a 6 month period (starting 2026/07/20). If found, it will place the integration into a "Reauthenticate" state, as well as create a new issue / persistent notification on how to re-authenticate the Spotify refresh token.
Updated spotifywebapipython package requirement to spotifywebapipython>=1.0.271.

thlucas · July 4, 2026, 11:37pm

FYI - just released a new version of the SpotifyPlus integration.

Be sure to check out the SpotifyPlus Card Dashboard as well.

This update fixes the Detected blocking call to import_module with args ('custom_components.spotifyplus.intent') exceptions that started appearing with the HA 2027.07.0 release (due to HA Core changes for Intent processing). Voice Assist intent imports are now delayed until HA initial startup has completed.

Please update existing issue 231 if you encounter any problems with this fix related to intent processing.

Thanks!

[ 1.0.203 ] - 2026/07/04

Updated Voice Assist intent imports to delay loading until after initial startup. This was causing Detected blocking call to import_module with args ('custom_components.spotifyplus.intent') exceptions starting with HA 2027.07.0 release.

Sofa_Surfer · July 7, 2026, 3:35pm

Hello Todd, I hope you are well! As usual, when I have some time i try to stay behind all updates and improvement you do (oh, thank you a lot for that!). I'm still in trouble with the transfer home-->car (it depends from many things, including IOS Spotify app availability when the phone is idle), but I see your integration run smoother every update!
Recently I've added to my home a 2016 DENON AVRX2800 with 2 multiroom, and I hope in the next years I will swap my 3 Sonos speakers with Heos, that will allow to have a full multiroom around the house and garden. But at the moment I have to deal with Sonos. I noticed now that if I transfer from Denon to Sonos I have this error:

Impossible execute action: spotifyplus/player_transfer_playback Validation error: SAM0001E - An unhandled exception occured while processing method "PlayerMediaResume". UPnP Error 701 received: Transition not available from 20.20.1.131

This happen if the Sonos comes from "idle" state, if I have already started a playlist on Sonos and moved to Denon, then transfer back to Sonos it's all good.
I'm using your spotifyplus.player_transfer_playback:

    service: spotifyplus.player_transfer_playback
    service_data:
      entity_id: media_player.spotifyplus
      device_id: >
        [[[ return variables.spotify_id; ]]]
      play: true

I'm not sure if I make a mistake, tried with/without play: and added device_id_from: without results. Can you please point me in the right direction? Possibly I'm missing something silly or maybe I can do some diagnose with the SmartInspect.

Thank you in advance

thlucas · July 7, 2026, 5:54pm

@Sofa_Surfer
It appears the current transport state of the Sonos device is paused, stopped, or transitioning. In this case, the SpotifyPlus tries to issue a call to PlayerMediaResume in order to place the device in a state that can be controlled by the Spotify Web API. The PlayerMediaResume is the actual call that is failing (not the PlayTransferPlayback).

You would need to run a SmartInspect trace to log the Sonos current transport state of the device. I am assuming it is "STOPPED", but not sure on that.

Does it transfer playback to the Sonos device if you make the exact same call to player_transfer_playback right after the failure? Just wondering if the first call to player_transfer_playback manages to wake it up from idle state, causing the second call to be successful.

thlucas · July 20, 2026, 7:31pm

What Happened?

It appears that Spotify just did some sort of “global” cleanup on their Authorization token database to expire all authorization and refresh tokens for Spotify Developer Apps that existed prior to their refresh token expiration changes. That would make sense, as in their 2026-06-18 Refresh Token Expiration blog post it references a “Existing apps: affected from July 20, 2026” for Spotify Developer Apps that previously existed (see excerpt below).

What is Broken?

This is causing the Home Assistant SpotifyPlus integration to fail with 400 Bad Request / setup failed errors when trying to initialize the integration.

Note that SpotifyPlus issue #235 is tracking this issue in detail from various users.

How Do I Fix It?

Follow the subsections below for the following:

Verify Spotify Developer App Settings
Remove SpotifyPlus Service and Application Credential, then Re-Add the Service

Verify Spotify Developer App Settings

Per the Spotify 2026 February Migration Guide, your Spotify Developer account is only allowed to have 1 Developer App defined per Spotify account. Prior to this change, you were allowed unlimited Developer Apps. I do not know what is happening on the Spotify end when you have 2 Developer Apps defined, but I would bet that there is logic in there somewhere to delete (or disable) the authorization token for the other Developer App(s). That is just a guess though. It’s obviously doing something to the other Developer App(s) authorization token, which causes the 400 Bad Request error - the fact that it’s not a invalid_grant type indicates it’s some other form of error.

If you have both the HA Spotify integration and the SpotifyPlus integration installed, then you will need to share the same Spotify Developer App client id / secret for both of the integrations. Note that each integration still requires their own Application Credentials though (e.g. both Application Credentials will use the same client id / secret).

Remove SpotifyPlus Service and Re-Add

I would suggest that you remove the SpotifyPlus service and its associated Application Credential, and then immediately re-add the service and go through the OAuth flow to re-authorize the integration to Spotify.

I still don’t know if both the HA Spotify and the SpotifyPlus integration can co-exist or not. I have both of them installed and running on my HA instance, but I have an older Spotify Developer App defined from a few years ago. There seems to be some differences between the old (e.g. pre 2026-02) and new (e.g. post 2026-02) Developer App definitions, but I am not sure what as of yet.

thlucas · July 21, 2026, 9:27pm

FYI - just released a new version of the SpotifyPlus integration.

Be sure to check out the SpotifyPlus Card Dashboard as well.

This release updates the spotifywebapipython package requirement to spotifywebapipython>=1.0.277. This change updated MakeRequest logic to check for 401 Access token missing and 403 - Player command failed: Premium required errors in the Spotify Web API response. Spotify made some sort of change in their API that is not recognizing a valid access token that is passed! The same request can be passed through after a slight delay successfully, which indicates it’s a problem on the Spotify side. This logic will retry the request a few times in a row, before giving up.

Note that the HA Spotify integration is still receiving the following errors quite frequently:

[homeassistant.components.spotify.coordinator] Unexpected error fetching spotify data

I say this only to point out that SpotifyPlus does not rely on the HA Spotify integration, so you can disable the HA Spotify integration if you wish (it will not affect SpotifyPlus). I am sure a fix will be forthcoming by the HA Spotify integration developers soon.

[ 1.0.207 ] - 2026/07/21

Updated spotifywebapipython package requirement to spotifywebapipython>=1.0.277. Updated MakeRequest logic to check for 403 - Player command failed: Premium required errors in the Spotify Web API response. Spotify made some sort of change in their API that is not recognizing a valid access token that is passed! The same request can be passed through after a slight delay successfully, which indicates it’s a problem on the Spotify side. This logic will retry the request a few times in a row, before giving up.

Diegocampy · July 24, 2026, 9:53am

Hi everyone, back again with another issue!

Yesterday, both my Spotify and Spotify Plus integrations (each configured with two accounts) were completely frozen and stopped working. Restarting Home Assistant or reloading the integrations didn’t help. However, when I tried adding a new account in Spotify by simply clicking the Add Account button, this menu popped up:

Then the web authentication process kicked off. I completed it for both accounts, and everything worked fine for Spotify.

However, when I tried doing the exact same thing with Spotify Plus, I ended up getting this error at the end:

What am I doing wrong? Thanks a lot!