funkwhale/docs/administrator_documentation/troubleshooting/backend.md

# Troubleshoot backend issues

The Funkwhale backend is made up of lots of moving parts. This guide shows you how to troubleshoot and gather information about the most important elements of the backend.

## Tools

If you have access to the Funkwhale backend, you can use logs to get more information about an issue.

- __Reverse proxy logs__ – check these logs if you have connectivity issues.

   ::::{tab-set}

   :::{tab-item} Nginx
   :sync: nginx

   ```{code} bash
   sudo tail -f /var/log/nginx/access.log # Follow the access log
   sudo tail -f /var/log/nginx/error.log # Follow the error log
   ```

   :::

   :::{tab-item} Apache2
   :sync: apache2

   ```{code} bash
   sudo tail -f /var/log/apache/access.log # Follow the access log
   sudo tail -f /var/log/apache/error.log # Follow the error log
   ```

   ````

- __API logs__ – check these if you are having issues with the Funkwhale app, federation, or imports.

   ::::{tab-set}

   :::{tab-item} Debian
   :sync: debian

   ```{code} bash
   journalctl -xn -u funkwhale-server
   ```

   :::

   :::{tab-item} Docker
   :sync: docker

   ```{code} bash
   docker-compose logs -f --tail=50 api # Follow the last 50 messages
   ```

   :::
   ::::

- __Celery logs__ – check these if a federation or import task isn't working.

   ::::{tab-set}

   :::{tab-item} Debian
   :sync: debian

   ```{code} bash
   journalctl -xn -u funkwhale-worker
   ```

   :::

   :::{tab-item} Docker
   :sync: docker

   ```{code} bash
   docker-compose logs -f --tail=50 celery # Follow the last 50 messages
   ```

   :::
   ::::

## Troubleshoot issues

### API issues

If the API isn't serving audio files, try the following:

- If you’re using Docker, check you have commented out the `MEDIA_ROOT` variable in your `.env` file.
- Check the `_protected/media` block in your webserver points to your media path. This is `/srv/funkwhale/data/media` by default.
- If you’re using the in-place import, check you have configured your media paths.  Check the `MUSIC_DIRECTORY_PATH`, `MUSIC_DIRECTORY_SERVE_PATH` and `REVERSE_PROXY_TYPE` variables in your `.env` file. Make sure the webserver can read these directories.

### Import issues

If you're having issues importing files, try the following:

- Check that the file is encoded in a supported format

:::{dropdown} Supported formats

- flac
- ogg
- mp3
- opus
- aac
- m4a
- aiff
- aif

:::

- Make sure your files play in another media player.
- Make sure your files are [tagged correctly](../../user_documentation/libraries/tag_music.md).
- Check the Celery logs for errors during the import.

### Federation issues

If you are having issues accessing federated content, try the following:

- Check that the remote library received your follow request and approved it.
- Trigger a library scan in the Funkwhale frontend.
- Check the Celery logs for errors during the scan.

### Memory tracing

If your Funkwhale server uses more memory than expected, you can check the footprint of requests. This requires a middleware to check memory allocation. To set up this middleware:

1. Add the middleware to your `.env` file.

   ```{code}
   ADDITIONAL_MIDDLEWARES_BEFORE=funkwhale_api.common.middleware.PymallocMiddleware
   ```

2. Enable memory tracing in your `.env` file.

   ```{code}
   PYTHONTRACEMALLOC=1
   ```

3. Restart your Funkwhale server.

   ::::{tab-set}

   :::{tab-item} Debian
   :sync: debian

   ```{code} bash
   sudo systemctl restart funkwhale.target
   ```

   :::

   :::{tab-item} Docker
   :sync: docker

   ```{code} bash
   docker-compose restart
   ```

   :::
   ::::

The middleware prints out the top 25 memory allocations to the API logs. You can use these to see what requests use the most memory.

To disable memory tracing:

1. Remove the middleware from your `.env` file.

   ```{code}
   # ADDITIONAL_MIDDLEWARES_BEFORE=funkwhale_api.common.middleware.PymallocMiddleware
   ```

2. Disable memory tracing in your `.env` file.

   ```{code}
   PYTHONTRACEMALLOC=0
   ```

3. Restart your Funkwhale server.

   ::::{tab-set}

   :::{tab-item} Debian
   :sync: debian

   ```{code} bash
   sudo systemctl restart funkwhale.target
   ```

   :::

   :::{tab-item} Docker
   :sync: docker

   ```{code} bash
   docker-compose restart
   ```

   :::
   ::::

## Get help

If you can't solve the issue yourself, ask the community for help. Check out the [get help](get_help.md) guide for information about where to ask your question and what details to provide.