Troubleshooting

Use this guide to determine whether a problem is caused by SpotX-Bash, Spotify itself, another client modification, or local app state.

For a SpotX-Bash bug report, the most important result is a reproducible comparison between completely stock Spotify and SpotX-Bash on the exact same Spotify version.

Start with the basic checks
Run a valid fresh-stock comparison
Use the automated cleanup
Test the exact same Spotify version
Remove Spicetify from the test
Snap testing
If the problem also happens on stock Spotify
What to include in a bug report

Start with the basic checks

Before removing anything:

Fully quit Spotify and open it again.
Reboot the computer.
Confirm the installed Spotify version is supported by the current SpotX-Bash release in the README.
If Spicetify is installed, restore it before diagnosing SpotX-Bash as described below.

If the issue remains and you need to determine whether SpotX-Bash is responsible, continue with a clean comparison.

Run a valid fresh-stock comparison

A valid stock test is not a memory of Spotify working previously. It is a fresh test performed immediately after a full cleanup and reinstall, before SpotX-Bash is applied.

Use this sequence:

full automated cleanup
  -> fresh Spotify install
  -> test the issue on completely stock Spotify
  -> record the exact Spotify version
  -> apply SpotX-Bash
  -> test the exact same issue again
  -> confirm the Spotify version is still identical

The following do not count as a valid stock baseline:

"Spotify worked before."
Testing stock Spotify several releases ago.
Testing a different Spotify version than the one patched by SpotX-Bash.
Only running SpotX-Bash --uninstall.
Only restoring xpui.spa or another patched file.
Reinstalling Spotify without clearing old app and cache state.
Testing before the full cleanup is complete.
Leaving Spicetify modifications applied while testing SpotX-Bash behavior.

The stock and patched tests must use the same exact Spotify version so that a Spotify version-specific regression is not mistaken for a SpotX-Bash regression.

Use the automated cleanup

For bug-report reproduction, use the current automated cleanup script and keep its complete Terminal input and output:

curl -sSL https://gist.github.com/jetfir3/f620e44fc246c1bed45ed040bbfa2d68/raw/uninstallify.sh | bash

The cleanup script requires an interactive Terminal because it asks for confirmation before removing each package or directory.

Follow its prompts so the installed Spotify package or app and its old app/cache state are removed. A transcript where relevant removal prompts were declined does not establish the full cleanup required by the bug form. After it finishes, do not apply SpotX-Bash yet.

For a bug report, paste the exact cleanup command you used and its complete output from start to finish. You may replace the username or home-directory portion of paths with $HOME, but do not remove Spotify paths, warnings, errors, or other information relevant to the cleanup.

Test the exact same Spotify version

After cleanup:

Install Spotify again.
Open it and sign in if needed.
Reproduce the exact issue while Spotify is completely stock.
Record the exact Spotify version shown by the client.
Apply SpotX-Bash and save the exact command plus its complete Terminal output.
Confirm the Spotify version did not change.
Reproduce the same issue again under the same conditions.

If the stock and patched versions differ, the comparison is not suitable for deciding whether SpotX-Bash introduced the behavior. Repeat the test with one identical Spotify version on both sides.

Do not update, downgrade, or change package variants between the stock and SpotX-Bash tests.

Remove Spicetify from the test

SpotX-Bash and Spicetify should not be used together because both projects modify Spotify client files. Combined installations are outside SpotX-Bash support. If you ignore that warning and use both anyway, SpotX-Bash must be applied before Spicetify.

For a setup that already uses both projects, remove Spicetify modifications before diagnosing SpotX-Bash:

spicetify restore

Do not reapply Spicetify until the SpotX-Bash test is complete.

spicetify restore is useful for removing Spicetify from a SpotX-Bash test, but it does not replace the full cleanup and reinstall required to establish a fresh stock baseline.

Snap testing

The Spotify Snap uses the dedicated spotx-snap.sh helper. Normal spotx.sh --uninstall or a custom -P path is not the correct way to return a rebuilt Snap to stock.

Restore the official store-managed Spotify Snap with:

bash spotx-snap.sh --restore

Then test the issue on the restored official Snap and record its exact Spotify version. Apply SpotX-Bash again with spotx-snap.sh to that same source version and repeat the test.

If restoring from the Snap Store changes the Spotify version, use the restored version as the new stock baseline and rebuild SpotX from that same version before comparing results.

For a full fresh cleanup rather than a Snap-only restore, use the automated cleanup procedure above.

If the problem also happens on stock Spotify

If the exact issue reproduces on freshly installed stock Spotify before SpotX-Bash is applied, the result does not show a SpotX-Bash regression.

At that point:

check Spotify's current Support site;
search the Spotify Community;
check Spotify Community Ongoing Issues;
test another Spotify version only after the stock-vs-SpotX comparison has been recorded, if you are investigating a Spotify client regression.

If a different Spotify version fixes the issue, report that as version-specific evidence rather than using the different version as the stock side of a SpotX-Bash comparison.

What to include in a bug report

If the issue is absent on fresh stock Spotify and returns after applying SpotX-Bash to the same exact version, include:

the cleanup command and complete Terminal output;
the exact fresh-stock Spotify version;
a written description of the result on fresh stock;
the exact SpotX-Bash command and complete Terminal output;
the exact Spotify version after applying SpotX-Bash;
a written description of the patched result and reproduction steps.

Screenshots or a short recording are optional. They can be useful for visual problems, but they are not required when the behavior is clearly described and the reproducible stock-vs-SpotX evidence is complete.

If SpotX-Bash fails before it can patch Spotify, such as during client/path detection or installation, enter N/A where the bug form permits it and explain the pre-patch failure. A stock-vs-patched comparison is not meaningful when no patched client was produced.

Before submitting, also check the FAQ and search open and closed SpotX-Bash issues.