Spotify provider: catalog endpoints broken for dev apps after Spotify API changes (Nov 2024) — artist albums, top tracks, search return empty

[obi1-source]

spotify_errors_for_issue.log

What server version of Music Assistant has the issue?

2.8.5

How is the MA server installed?

Docker Container

Mandatory: Carefully read the Troubleshooting FAQ and confirm that

• I have examined the logs and tried to resolve this issue
• I have fixed any errors or warnings in the logs that relate to tags
• I am not running MA across a VPN, VLAN, subnet, behind a firewall, or using local SSL or have any other complex network setup
• I am not using or have disabled tools such as AdGuard, Pi-hole or pfSense and retested
• I have checked my network setup to ensure mDNS/multicast is not being blocked
• I have reviewed the Open and Closed Issues and Discussions
• I have reviewed the applicable player or music provider documentation
• I have reviewed the MA Status Page
• I have tried restarting MA and rebooting the host

As Applicable: Carefully read the Troubleshooting FAQ and confirm that

• If using HA, I have confirmed the internal URL is set correctly
• I have tried a wired connection for issues related to interrupted or poor playback quality
• If the problem relates to a device then I have checked the device settings
• If it is a frontend issue, I have tried a different widely used browser
• For voice problems, I have sought help elsewhere before returning here
• For playback problems, I have recycled power to the physical device

The problem

Summary

Since Spotify's API changes on November 27, 2024,
developer apps without Extended Quota Mode no longer have access to catalog endpoints.
Music Assistant's Spotify provider calls these endpoints using the user's dev session,
which causes silent failures (empty sections) in the UI.

Affected sections

UI section	Endpoint called	Result
Artist → Albums	GET /v1/artists/{id}/albums	empty
Artist → Top Tracks	GET /v1/artists/{id}/top-tracks	empty / error toast
Track detail → "Appears on"	GET /v1/search	empty
Track detail → "Versions" / provider details	GET /v1/search	empty

Root cause

Music Assistant maintains two Spotify sessions:

• Global session — uses MA's own client ID → has catalog access ✅
• Dev session — uses the user's registered client ID → restricted since Nov 2024 ❌

get_artist_albums, get_artist_toptracks, and search all call _get_data() without
use_global_session=True, so they use the restricted dev session.

The Spotify API returns HTTP 400 with {"error": {"status": 400, "message": "Invalid limit"}} —
the error message is misleading; the actual cause is missing catalog access for the dev app,
not an invalid parameter.

Additionally, _get_data() passes country="from_token" and market="from_token" to all
requests. Both values were deprecated by Spotify in the November 2024 changes and also cause
400 errors.

Fix

1. get_artist_albums — add use_global_session=True

async for item in self._get_all_items(                    
    f"artists/{prov_artist_id}/albums",                                                                                                                                                                          
    include_groups="album,single,compilation",                                                                                                                                                                   
    use_global_session=True,  # required since Spotify API changes Nov 2024                                                                                                                                      
)                                                                                                                                                                                                                
                                                          
2. get_artist_toptracks — add use_global_session=True + handle residual 403                                                                                                                                      
                                                          
try:                                                                                                                                                                                                             
    items = await self._get_data(endpoint, use_global_session=True)                                                                                                                                              
except aiohttp.ClientResponseError as err:
    if err.status == 403:                                                                                                                                                                                        
        self.logger.warning(                              
            "Spotify top-tracks unavailable for artist %s (403 Forbidden) — "                                                                                                                                    
            "endpoint may be restricted for this app type. Returning empty list.",                                                                                                                               
            prov_artist_id,                                                                                                                                                                                      
        )                                                                                                                                                                                                        
        return []                                                                                                                                                                                                
    raise                                                 

3. search — add use_global_session=True

api_result = await self._get_data(
    "search", q=search_query, type=searchtype, limit=page_limit, offset=offset,                                                                                                                                  
    use_global_session=True,  # required since Spotify API changes Nov 2024                                                                                                                                      
)                                                                                                                                                                                                                
                                                                                                                                                                                                                 
4. _get_data — replace deprecated from_token parameter values                                                                                                                                                    
                                                          
# Remove entirely:                                                                                                                                                                                               
kwargs.setdefault("country", "from_token")                
                                                                                                                                                                                                                 
# Replace with actual country code:
# kwargs.setdefault("market", "from_token")                                                                                                                                                                      
raw_locale = self.mass.metadata.locale                    
market = (                                                                                                                                                                                                       
    raw_locale.split("_")[-1] if "_" in raw_locale                                                                                                                                                               
    else raw_locale.split("-")[-1] if "-" in raw_locale                                                                                                                                                          
    else "US"                                                                                                                                                                                                    
)                                                         
kwargs.setdefault("market", market)                                                                                                                                                                              
                                                          
Environment

- Music Assistant running in Docker                                                                                                                                                                              
- Spotify provider configured with a self-registered developer app (no Extended Quota Mode)
- Issue is reproducible for any artist or track in the library                                                                                                                                                   
                                                                                                                                                                                                                 
References                                                                                                                                                                                                       
                                                                                                                                                                                                                 
- Spotify announcement: https://developer.spotify.com/blog/2024-11-27-changes-to-the-web-api                                                                                                                     
- Spotify Extended Quota Mode: https://developer.spotify.com/documentation/web-api/concepts/quota-modes

## Verified fix                                                                                                                                                                                                  
                                                                                                                                                                                                                 
I have applied all four changes locally to `music_assistant/providers/spotify/provider.py`                                                                                                                       
and confirmed that artist albums, top tracks, and track detail sections ("Appears on" and                                                                                                                        
"Versions") all populate correctly after the fix. Happy to provide the full patched file                                                                                                                         
if helpful. 


### How to reproduce

## Steps to reproduce                                                                                                                                                                                            
                                                                                                                                                                                                                 
1. Set up Music Assistant with a self-registered Spotify developer app                                                                                                                                           
   (registered at https://developer.spotify.com/dashboard) without Extended Quota Mode                                                                                                                           
2. Open any artist page → the "Albums" section is empty                                                                                                                                                          
3. Open any artist page → the "Top Tracks" section is empty or shows an error toast                                                                                                                              
4. Open any track detail page → the "Appears on" and "Versions" sections are empty                                                                                                                               
                                                                                                                                                                                                                 
No special artist or track is required — the issue affects all content.                                                                                                                                          
                                                          
## Expected behavior                                                                                                                                                                                             
                                                          
Albums, top tracks, and track detail sections populate with data from Spotify.

## Actual behavior                                                                                                                                                                                               
 
Sections remain empty. The Spotify API returns HTTP 400 with the misleading error message                                                                                                                        
`{"error": {"status": 400, "message": "Invalid limit"}}` — the actual cause is missing
catalog access for developer apps without Extended Quota Mode.           

### Music Providers

Spotify (configured with a self-registered developer app, no Extended Quota Mode)

### Player Providers

(not relevant for this issue — the bug occurs before any playback, during metadata/catalog lookups) 

### Full log output

## Log output                                                                                                                                                                                                    
                                                          
The following warnings were captured during debugging by adding temporary diagnostic                                                                                                                             
logging to `_get_data()` (logging the raw response body on HTTP 400):
                                                                                                                                                                                                                 
WARNING  Spotify 400 artists/{id}/albums — {"error": {"status": 400, "message": "Invalid limit"}}                                                                                                                
WARNING  Spotify 400 artists/{id}/top-tracks — {"error": {"status": 400, "message": "Invalid limit"}}                                                                                                            
WARNING  Spotify 400 search — {"error": {"status": 400, "message": "Invalid limit"}}                                                                                                                             
                                                          
Note: `{id}` replaced for brevity. The error message "Invalid limit" is misleading —                                                                                                                             
no limit parameter was invalid. The actual cause is missing catalog access for the dev app.   

[spotify_errors_for_issue.log](https://github.com/user-attachments/files/26949535/spotify_errors_for_issue.log)

### Additional information

## Additional information                                                                                                                                                                                        
                                                                                                                                                                                                                 
The fix has been verified locally. All four changes were applied to                                                                                                                                              
`music_assistant/providers/spotify/provider.py` and confirmed working:                                                                                                                                           
artist albums, top tracks, and track detail sections ("Appears on" and "Versions")                                                                                                                               
all populate correctly after the fix.                                                                                                                                                                            
                                                                                                                                                                                                                 
The error message `"Invalid limit"` returned by the Spotify API is misleading and made                                                                                                                           
diagnosis significantly harder. The actual cause is that Spotify's November 2024 changes                                                                                                                         
restricted catalog endpoint access for developer apps without Extended Quota Mode —                                                                                                                              
the limit parameter itself is not at fault.                                                                                                                                                                      
                                                                                                                                                                                                                 
A full write-up of the root cause analysis and all code changes is available on request.      

### What version of Home Assistant Core (if used) are your running

26.4.3

### What type of installation are you running?

Home Assistant Container

### On what type of hardware are you running?

Generic x86-64 (e.g. Intel NUC)

### Have you included ALL of the information specified in the Troubleshooting FAQ or explained why you cannot

- [x] Yes

[github-actions]

⚠️ Issue Template Validation

Thank you for reporting this issue! However, there are some problems with the issue template:

• Please ATTACH the log file instead of pasting it. See instructions in the template.

Please update your issue with the missing information. Providing complete information helps us resolve issues faster. See the Troubleshooting Guide for more details.

[OzGav]

Please dont post a wall of AI generated text. This is already known about and is being discussed,

[obi1-source]

Sorry for the lengthy post. Good to know it's already being worked on.
Could you point me to the relevant issue or discussion? I couldn't find one when I searched before posting.

[OzGav]

music-assistant/server#3762

But the core team is also discussing it on Discord which you would not be able to find.

[obi1-source]

Thanks for the link! Great to see it's already being addressed in #3762.