Troubleshooting

This page presents some guides to help fix common problems. If your problem is not listed, or the steps below don't work, please file an issue including verbose logging. Please use proper formatting, and past your logs in code blocks.

Please note that the issue tracker is not a support forum. It is primarily used to submit bugs, improvements or feature requests. We are glad to help you and make sure the problem is not caused by Headphones. Please understand that we don't have a crystal ball that can look into your problem. Every problem and system is different.

Furthermore, don't expect from us that we provide a complete answer step-by-step. We voluntarily try to help you, so please understand that we don't have unlimited time and tendency to help you in detail. Therefore, we assume you understand what we reply. If not, we advice you to look for support on internet forums.

See the README.md for more information.

First of all: toggle verbose

Headphones does not turn on verbose logging (also known as debug information) for efficiency reasons. While this information is extremely useful in solving problems, it is the first thing that you should enable in case of problems. There are two ways of toggling verbose mode.

• Modify the command line arguments to include the --verbose (or -v) option. Do note that the --verbose option may conflicts with --quiet (web log only) and --daemon (no terminal output), but it will always print to the web log.
• Toggle verbose mode via http://ip:port/toggleVerbose. You should see in the web log if verbose is turned on or off. This option is not permanent, and will be restored on the next start. With this option, you cannot log startup errors, since Headphones should be started to toggle this.

The second option will be the easiest option in most cases, especially for Synology users.

Second of all: rule-out human error

There are a lot of issues that can be solved by just reviewing your settings. Before continuing (or posting an issue), consider the following general advice:

• Do you have Python 2.6 or 2.7 installed? Run python --version to see which version you have installed. Python 3.x is NOT supported. Some distributions favor Python 3.x above Python 2.x as default interpreter.
• Review your settings. If possible, try to start from scratch (just run a separate install from another directory), to isolate the problem. For instance, see this issue #1985.
• Check the permissions. Under Linux, ls -al should list the files in the current folder. The user owning the files is shown too, which should match the running user.
• Try to start Headphones directly, not via an init script or service. Type python Headphones.py -h to see how to start it directly, and as a tip: make sure the paths to your configuration files are correct!
• Use Google! It's for a reason we put so much logging in Headphones. Sometimes, Google just yields the answer by copy-pasting the error message.

Cannot reach MusicBrainz server

Symptoms:

WARNING Attempt to query MusicBrainz for XXXX failed (retried 3 times, caused by: HTTP Error 502: Bad Gateway)

Solutions:

• In case you're on the VIP server:
  • Make sure you have selected the right mirror under 'Advanced Settings' (could relate to 5xx errors).
  • Check your credentials (you probably get code 401)
  • Reset your credentials, see here
• Increase sleep interval. For most mirrors, you need at least 1 second, to not hammer the remote server.
• Try a different mirror
• Try at a later moment — the mirror may be updating.
• Setup your own mirror

Request errors

Symptons:

You see messages similar to this, while Headphones is searching:

ERROR Request raised HTTP error with status code 401 (local request error).

Solutions:

• Verify your search providers
• See if the status code can help you:
  • 401 — Unauthorized: check if credentials are required.
  • 403 — Access denied: check if your credentials are correct.
  • 404 — Requested URL not found. Turn on verbose to see the URL that is being requested. Note that 404 isn't an error per se. For instance, the KAT search provider returns 404 to indicate no results.
  • 5xx — Remote server error, nothing you can do right now.

(Auto) update does not work

Symptoms: Headphones tells you there is a new version available, but an update fails. The version number does not change.

Or:

After an update, Headphones does not start anymore.

Solutions:

First of all, make sure Headphones has write access to the installation.

The auto-update function of Headphones uses Git to update to the latest version. It may happen that the auto update fails, and manual action is required. It is assumed that you have a recent version of Git installed.

For Synology users it may be necessary to specify the full path to the git binary.

Note: in some cases, you'll have to cleanup the *.pyc files that Python generates. These files are byte-compiled source files. Since v0.5.1, a script is included in contrib/clean_pyc.sh to clean these files for you.

Manual update

Use the following commands to reset your repository. Backup your configuration and database files, just in case.

• cd /path/to/heapdhones
• git branch should list either master or develop.
• git remote show origin should exist and point to https://github.com/rembo10/headphones
• git reset --hard — this WILL overwrite all local changes! It will spare your config and database.
• git remote update
• git pull origin master or git pull origin develop

Reinstallation

There are some issues with specific version of Headphones for Synology, where the first method will not work (see issues #1770, #1742 and #1774). The following provides some steps to reinstall Headphones, but should be tailored to your specific installation.

• cd /path/to/heapdhones
• Backup your database and config file. In my case, I just copy them to the parent folder. Make sure you have copied them!
  • cp headphones.db* ../
  • cp config.ini ../
• cd ..
• rm -rf /path/to/headphones
• git clone https://github.com/rembo10/headphones /path/to/headphones
• In case you run Headphones as a different user, make sure the Headphones user owns the directory for writing.
  • chown -R headphones:headphones /path/to/headphones

Downgrade to previous version

Sometimes, you just want to go back to an older version. For instance, there is no update or fix available (yet) for a problem you did not have in an older version. Backup your configuration and database files, just in case.

• cd /path/to/heapdhones
• git log, which should give a list of all changes.
  • Pick a commit hash (long string of letters and digits)
• git reset --hard PUT_HASH_HERE — this WILL overwrite all local changes! It will spare your config and database.

Alternatively, since v0.5.1, you can run contrib/downgrade.sh <path to data folder>. This should restore Headphones to the last version that started successfully. You need to have Git installed, and it's Unix-only.

SSL-enabled servers/indexers/search providers don't work

Symptoms:

When using SSL-enabled search providers (ones starting with HTTPS in their URL), it fails to connect and return search results. Optionally, if I surf to the URL, my browser gives a certificate warning.

Solutions:

• Check if the server actually uses HTTPS.
• Ask the server operator to fix the certificate.
• Install the Certificate Authority, so the certificate is trusted by the system
• Disable certificate check in Headphones. This poses a security risk, because from now on, all HTTPS connections are susceptible to man-in-the-middle attacks!
  • Make sure Headphones is configured and running
  • Quit Headphones. Make sure it quitted!
  • Open config.ini in your favorite text editor
  • Set verify_cert_ssl to 0. The key should under the [Advanced] section, and by default, it should mention the value 1
  • Save the file.
  • Start Headphones again.

Settings cannot be saved or disappear

Symptoms: When I settings are saved, they don't persist.

Or:

When I go to some field, it stays empty, while others save perfectly.

Solutions:

• Make sure your config file exists and is writable.
• Web server settings (such as username/password) are only effective when Headphones is restarted
• Try to access Headphones directly by IP (no proxy, forwarding etc. See issue #1858)
• Verify the log that settings are saved. There should be a log entry when settings are saved.
• Disable auto complete. There are reports of browsers autocompleting fields.

Snatched downloads aren't picked up by downloader

Symptoms: When Headphones snatches a release, it doesn't appear in my downloader (NZBget, SABnzbd, Transmission, uTorrent, black hole).

Solutions:

• If some error occurs, they should appear in the logs. Don't forget to check the log file of your downloader.
• Check the credentials for the API of your downloader, on both sides.
• In case of black hole:
  • Verify that if you manually put a file in the watch directory, the downloader processes it.
  • Does the black hole directory of Headphones match the watch directory of your downloader?
  • Does the downloader have read/write permissions on the watch directory?
  • Check the watch interval settings of your downloader.

Headphones installed as daemon does not work

Symptoms: When I installed Headphones as a daemon, it does nothing when I start it (e.g. service headphones start).

Or:

Headphones does not run at startup, even though I installed it as daemon.

Solutions:

• See if it is not actually running. Under Ubuntu/Debian ps awx | grep Headphones should list a process with it's startup arguments if it has started.
• Check the log files.
• Make sure you have the service enabled. For instance, under Ubuntu/Debian you have to mark a service to startup on boot with sudo update-rc.d headphones defaults. Refer to Install as a daemon for more information.
• Make sure that the daemon user has write permissions to the data folder, and that the data folder exist. A common mistake is that Headphones was first setup to run as normal, and then installed as daemon with a special daemon user. In most cases, the daemon user cannot access normal user's files.
• Make sure no other service is running on the configured port. Also note that ports below 1024 require root privileges.
• Debug the startup script. One way is to edit the startup script and remove the --daemon and --quiet option from the launch options and add the --verbose option. For instance, see Line 112 in the Ubuntu launch script. Now when you start the script, it should start in the foreground. Any errors will now be printed to console or log file.

Database problems

Symptoms: I regularly see Database is locked in the logs.

or

I get exceptions such as DatabaseError: database disk image is malformed.

Solutions:

• In case of locked databases, try to increase interval settings for scanning and so forth. If you have a huge library, scanning takes a while. Any other operations may already be started, causing locking conflicts.
• In case of corruption, see #1178, #1053, #1676 or #1981.