spotifyaio 2.0.2: "Field items of type PlaylistTracks is missing" with current Spotify API

[Belov-Dev]

The problem

Hi! when I tried installing the Spotify integration - it fails to set up with the following error:

Field "items" of type PlaylistTracks is missing in Playlist instance

This makes media_player.spotify_* entities permanently unavailable.

Root cause:

The Spotify API returns simplified Playlist objects in list responses (e.g. when fetching a user's playlists). In these objects, tracks contains only href and total — without the items array:

  {                                                                                                                                                                                                          
    "tracks": {                                             
      "href": "https://api.spotify.com/v1/playlists/.../tracks",
      "total": 42                                                                                                                                                                                            
    }
  }                                                                                                                                                                                                                       

spotifyaio's Playlist model treats items: PlaylistTracks as a required field and crashes during deserialization.

What version of Home Assistant Core has the issue?

core-2026.4.0

What was the last working version of Home Assistant Core?

core-2026.4.0

What type of installation are you running?

Home Assistant OS

Integration causing the issue

spotifyaio version: 2.0.2

Link to integration documentation on our website

No response

Diagnostics information

No response

Example YAML snippet

Anything in the logs that might be useful for us?

Additional information

Fix:

In spotifyaio/models.py:

1. Make Playlist.items optional

class Playlist(BasePlaylist):

      items: PlaylistTracks | None = None  # was: items: PlaylistTracks

2. Guard against missing items in PlaylistTracks

@classmethod

  def __pre_deserialize__(cls, d: dict[str, Any]) -> dict[str, Any]:                                                                                                                                         
      items = [item for item in (d.get("items") or []) if not item.get("is_local", False)]
      return {"items": items}  

[rqbanerjee]

Encountering this with Core 2026.6.3. It appears to be an issue in the upstream library. Hoass will need a version bump in the manifest file when spotifyaio makes a fix and release.