Troubleshooting¶
Examples on this page use the PyPI command spotify_profile_monitor. If you installed the manual script, replace that command with the matching command prefix.
Doctor Preflight¶
Run Doctor before unattended monitoring:
Doctor shows the current check phase then reports the Python environment and required dependencies, config and dotenv files, numeric settings, output destinations, Spotify authentication, metadata backend, connectivity, one optional target and notification settings. When optional legacy OAuth app credentials and a target playlist are available, Doctor makes a live playlist metadata request. This distinguishes successful token issuance from actual legacy playlist access. If Spotify issues a token but rejects the playlist endpoint, Doctor warns that normal monitoring will use the web-player backend. It names the dotenv file it loaded and lists which secrets are in effect and whether each one came from the dotenv file, an environment variable or the configuration file. Secret names are listed, never their values.
When a terminal is interactive and passive checks pass, Doctor separately offers one real email test and one real webhook test. Each prompt defaults to No. Warnings do not fail the command. A failed check or approved delivery test returns a nonzero exit status.
Choosing the Right Logging Level¶
- Default mode keeps startup output compact and reports profile changes, warnings and errors
- Verbose mode (
--verbose) adds the complete startup summary plus infrequent operational transitions such as token refreshes or metadata backend changes - Debug mode (
--debug) adds sanitized HTTP flow, scheduling details and internal diagnostics
Recoverable failures use a short Error, To fix and relevant guide format. Repeated monitoring failures keep the short error visible but suppress unchanged recovery instructions until the operation succeeds or the failure category changes. Raw exception detail is shown only in debug mode.
Cookies, tokens, passwords, authorization headers and webhook URLs are redacted from verbose and debug output, so sanitized output is safe to attach to a GitHub issue.
Start with --doctor. If the suggested fix does not resolve the issue, retry with --debug and include only sanitized output when opening an issue.
Common Problems¶
| Symptom | Likely cause | Where to look |
|---|---|---|
sp_dc cookie rejected or expired |
The monitoring account signed out or Spotify rotated the session | Spotify sp_dc Cookie then rerun --set-sp-dc or browser import |
Playlists show as [ RESTRICTED ] |
Spotify returns 403 or 404 for that playlist through both backends | Restricted Playlists |
| Followings or followers are missing | The active token source does not expose them | Spotify access token source |
Username search (-s) returns nothing |
SP_SHA256 is not configured |
Spotify sha256 |
Refresh token expired in client mode |
The intercepted login request body is stale | Spotify Desktop Client then re-export and send SIGHUP |
| Emails never arrive | Incomplete SMTP settings | SMTP Settings then run --send-test-email |
| Webhook alerts never arrive | Provider mismatch or a redirecting destination | Webhook Settings then run --send-test-webhook |
| "null bytes" error reading the config file | PowerShell redirection wrote UTF-16 | Configuration File |
| Artwork missing from alerts | The optional artwork extra is not installed | Install from PyPI |
Escape sequences such as [36m printed as text, or no colour at all |
The terminal cannot display ANSI colour, or colour was switched off by --no-color, COLORED_OUTPUT, NO_COLOR, a redirect or an unset TERM |
Terminal Colours |