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:

spotify_profile_monitor --doctor <spotify_target>

Each row is marked [PASS], [WARN], [FAIL] or [SKIP], colour-coded by status when colour output is on. Every [WARN] and [FAIL] row carries an indented To fix: line under its marker, plus a Guide: link when a documentation page covers that row. A [SKIP] row names a check that could not run and says why.

Doctor checks Environment, Configuration, Authentication, Metadata, Connectivity, Target and Notifications. It reports active files, secret sources, output destinations, timezone and TLS verification. Secret values are not displayed. Notification checks validate email sign-in and webhook settings without sending a message.

If legacy OAuth app credentials and a playlist are available, Doctor checks playlist access. If Spotify accepts the credentials but rejects the playlist request, it warns that monitoring will use the web-player backend.

In an interactive terminal, Doctor offers one real test message per ready notification channel. Each prompt defaults to No and requires separate approval. Ctrl+C ends the report. Warnings do not fail the command. A failed check or approved delivery test returns a nonzero exit status.

Follow the report's Next steps after correcting any failed checks. The printed start command uses the configuration and dotenv files you checked.

Common Problems¶

Every failure is reported in the same three-part shape: what went wrong, a To fix: action and a Guide: link to the page that covers it. The fix command matches how you installed the tool and carries the --config-file or --env-file you started with, so it can be pasted as it is. --debug appends a Technical detail: line for bug reports. Secrets are redacted from all three.

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 `spotify_profile_monitor --send-test-email`
Webhook alerts never arrive	Provider mismatch or a redirecting destination	Webhook Settings then run `spotify_profile_monitor --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	Terminal Colours Look Wrong
`Spotify did not answer in time`, `Spotify could not be reached` or `Spotify is temporarily unavailable`	A network problem between this machine and Spotify or a Spotify outage	Connection Problems
`This process ran out of file descriptors`	The operating system limit on open files was reached	Too Many Open Files

A continuing outage produces a * Monitoring degraded reminder once an hour, even when the liveness reminder is switched off. * Monitoring recovered marks recovery. Use --verbose to see the first failed check.

Connection Problems¶

Spotify did not answer in time and Spotify could not be reached mean a check got no answer from Spotify. Spotify is temporarily unavailable means Spotify answered with a server error. The report names the interval after which the check is retried, so a short outage needs no action. A failure that lasts produces the hourly Monitoring degraded reminder and Monitoring recovered when it clears.

If the failure continues, check the internet connection, DNS and any firewall or proxy between this machine and Spotify. A secure connection could not be established is a TLS problem, see TLS Verification. A server error that lasts is a Spotify outage, so wait for it to end.

To confirm that Spotify is reachable from this machine, run:

spotify_profile_monitor --doctor

Too Many Open Files¶

This process ran out of file descriptors means the operating system limit on open files was reached. It is a local limit and not a Spotify problem. Raise it with ulimit -n 4096 in the shell that starts the tool or set LimitNOFILE= in the systemd unit, then restart the tool.

Terminal Colours Look Wrong¶

If escape sequences such as [36m appear as literal text, the terminal does not understand ANSI colour. Start the tool with --no-color or set COLORED_OUTPUT = False in the configuration file. On Windows, pip install colorama fixes the classic Command Prompt.

If colour is missing where you expect it, check in this order: --no-color on the command line, COLORED_OUTPUT in the configuration file, a NO_COLOR environment variable and whether output is redirected or piped. Colour is switched off in all of those cases and also when TERM is unset or set to dumb.

Log files never contain colour by design. To colour a saved log while reading it, see Coloring Log Output with GRC.

To change which colours are used, see Terminal Colours.

Choosing the Right Logging Level¶

Default mode reports activity changes and important errors
Verbose mode (--verbose) adds occasional state changes, a line naming where each delivered alert went and a complete startup summary without private values. Set DELIVERY_CONFIRMATIONS = False to keep verbose mode without those delivery lines
Debug mode (--debug) adds sanitized request flow, scheduling details and internal diagnostics

Delivery confirmations name the recipient or webhook provider. DELIVERY_CONFIRMATIONS = False hides these optional success messages. Monitoring events, send attempts and errors remain visible.

Both --verbose and --debug show the complete startup summary, including notification settings and credential sources. Use it to check which configuration is active without displaying private values.

Start with --doctor. If the suggested fix does not resolve the issue, retry with --debug and include only sanitized output when opening a GitHub issue.

Verbose and Debug Output¶

--verbose adds the decisions a run made, in the same * lines as the rest of the output:

spotify_profile_monitor <spotify_target> --verbose

--debug traces what the tool is doing in timestamped [DEBUG HH:MM:SS] lines:

spotify_profile_monitor <spotify_target> --debug

Lines with details read Operation: key=value, key=value. Fields depend on the operation. Some results report outcome=OK, failed, degraded or skipped.

Installation and Command Problems¶

If Python or pip is missing, use the Python install walkthrough.

If spotify_profile_monitor is not found after installation, close the terminal and open it again. On Windows with Python Install Manager, run py install --refresh to refresh command aliases. For a pipx installation, run pipx ensurepath then reopen the terminal. If you downloaded the script, use the manual command from its directory.

If pip reports an externally managed environment, follow the pipx steps in Installation. Use pipx upgrade spotify_profile_monitor for later upgrades.

If the tool cannot import a dependency, install the dependencies with the same Python interpreter that runs the script. On macOS or Linux use python3 -m pip install -r requirements.txt. On Windows use python -m pip install -r requirements.txt. Match the requirements file to your downloaded script.

If a new terminal cannot find your saved settings, return to the directory used during setup or pass both --config-file and --env-file explicitly. Run spotify_profile_monitor --doctor to see which settings are loaded.

Invalid saved settings and state¶

Timing values must be finite and within the documented range. Normal startup checks effective timing settings before monitoring. A configuration syntax error reports its file, line number and parser message without echoing source text that may contain credentials.

If a saved playlist, follower or following file has an invalid structure, monitoring stops before replacing it. Correct the named file or move it aside to start a fresh baseline. Keep a copy if you need the old history. Older valid records and extra trailing metadata remain accepted, including files from releases before 3.9 that hold null where the count or the list was unavailable.

Malformed path settings and color-theme values are reported by Doctor with the setting name. Invalid color values are ignored while rendering help so you can still find the configuration commands.