Skip to content

Troubleshooting

Jump to bottom Edit New page
zerojay edited this page Apr 2, 2016 · 58 revisions

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.

See the README.md for more information.

Table of contents

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.

  • Start Headphones with the --verbose option. Do note that the --verbose option may conflicts with --quiet (web log only) and --daemon (no terminal output).
  • Toggle verbose mode temporary via http://ip:port/toggleVerbose. You should see in the web log if verbose is turned on or off.

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:

  • 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

Cannot access Headphones from another device or computer

By default, Headphones runs on localhost only, which only listens for connections coming from the local machine. To allow access from your entire network, change the http host from 'localhost' to '0.0.0.0', and then restart Headphones.

If you install Headphones on a headless machine, run it, stop it, edit the file and run it again.

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.
    • 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/headphones
  • git branch should list eith/er 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/headphones
  • 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/headphones
  • 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 if it's a self-signed one.
  • Fix the dependencies to enable SNI in Python 2.x.
  • 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! Your privacy level will degrade! For instance, your provider could replace the certificate so it can decrypt your connection.
    • Make sure Headphones is configured and running
    • Quit Headphones. Make sure it quitted! You need to stop the service, otherwise the changes you make will disappear.
    • 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. See #2313 for some more info.
  • 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.

Scheduled tasks don't run

Symptoms: My downloads in the post processing folder aren't picked up.

Solutions:

  • Scheduled post processing (download scan interval) only picks up snatched downloads, not ones you put in the folder manually. For instance, if Headphones snatches a download, it will determine a folder name (e.g. Folder A/). Then, it will only post process that download automatically if it is put in this folder, not if your download client puts it in something else (e.g. Folder B/, or even Completed/Folder A).
  • Make sure you have configured the intervals properly. Setting an interval to zero disables a task. Every time you save the configuration, it will restart scheduling!
  • Clean *.pyc files. For Unix users, there is a script in the contrib/ folder. These files contain compiled Python code, and normally they should be regenerated if the source files have changed. However, in some cases, this does not happen.
  • Check the log files:
    • When you start Headphones (or save settings), it will mention something like (Re-)Scheduled 6 background tasks. Confirm this corresponds to the tasks you have enabled or disabled.
    • As of version v0.5.2, all scheduled tasks will output to (debug) log when they start. For post processing, this message will be Checking download folder for completed downloads.
Add a custom footer
Add a custom sidebar
Clone this wiki locally