Skip to main content

Troubleshooting Checklists

You are welcome to ask for help in our discussions page

Connection Fails​

If your browser cannot connect to the Web UI even after waiting a few minutes, run this command to display the last 100 log messages (omit --tail=100 to see all):

docker compose logs --tail=100

Before reporting a bug, whould you please the following things:

  • Check the logs for messages like disk full, disk quota exceeded, no space left on device, read-only file system, error creating path, wrong permissions, no route to host, connection failed, and killed:
  • Make sure you are using the correct protocol (default is http), port (default is 4823), and host (default is localhost):
  • Note that HTTP security headers will prevent the app from loading in a frame (override them)
  • Verify your computer meets the system requirements
  • Go through the checklist for fatal server errors

Should MariaDB get stuck in a restart loop and Starsky can't connect to it, this indicates a memory, filesystem, or other permission issue:

mariadb: mysqld: ready for connections.
mariadb: mysqld (initiated by: unknown): Normal shutdown
starsky: dial tcp 172.18.0.2:3306: connect: no route to host
mariadb: mysqld: Shutdown complete

To enable debug mode, set app__verbose to true in the environment: section of the starsky service (or use the -v flag when running the starsky command directly):

services:
  starsky:
    environment:
      app__verbose: "true"

Then restart all services for the changes to take effect. It can be helpful to keep Docker running in the foreground while debugging so that log messages are displayed directly. To do this, omit the -d parameter when restarting:

docker compose stop
docker compose up

!!! note "" If you see no errors or no logs at all, you may have started the server on a different host and/or port. There could also be an issue with your browser, browser plugins, firewall settings, or other tools you may have installed.

!!! tldr "" The default Docker Compose config filename is docker-compose.yml. For simplicity, it doesn't need to be specified when running the docker-compose command in the same directory. Config files for other apps or instances should be placed in separate folders.

Docker Doesn't Work​

↪ Getting Docker Up and Running

MariaDB Issues​

↪ Troubleshooting MariaDB Problems

MySQL Errors​

↪ Official support for MySQL 8 is discontinued

Bad Performance​

↪ Performance Tips

↪ Solving Windows-Specific Issues

Fatal Server Errors​

Fatal errors are often caused by one of the following conditions:

We recommend checking your Docker Logs for messages like disk full, disk quota exceeded, no space left on device, read-only file system, error creating path, wrong permissions, no route to host, connection failed, and killed:

  • If a service has been "killed" or otherwise automatically terminated, this points to a memory problem (add swap and/or memory; remove or increase usage limits)
  • In case the logs show "disk full", "quota exceeded", or "no space left" errors, either the disk containing the storage folder is full (add storage) or a disk usage limit is configured (remove or increase it)
  • Errors such as "read-only file system", "error creating path", or "wrong permissions" indicate a filesystem permission problem
  • Log messages that contain "no route to host" indicate a problem with the database or network configuration (follow our examples)

Start a full rescan if necessary, for example, if it looks like thumbnails or pictures are missing.

App Not Loading​

If the app doesn't load in your browser when you navigate to the server URL, you can check the browser console for helpful errors and warnings. Sometimes you just need to wait a moment, for example, if you are using a slow wireless connection or the server was started only a few seconds ago. In case this does not help:

  • You are using an incompatible browser (try another browser)
  • JavaScript is disabled in your browser settings, so you only see the splash screen (enable it)
  • JavaScript was disabled by a browser plugin (disable it or add an exception)
  • Your browser cannot communicate properly with the server, e.g. because a Reverse Proxy, VPN, or CDN is configured incorrectly (check its configuration and try without)
  • HTTP security headers prevent the app from loading in a frame (override them)
  • An ad blocker or other plugins block requests (disable them or add an exception)
  • There is a problem with your network connection (test if other sites work)
  • You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

Missing Pictures​

If you have indexed your library and some images or videos are missing, first check the logs In case the application logs don't contain anything helpful:

Depending on the cause of the problem, you may need to perform a full rescan once the issue is resolved.

Zip Archives​

When you try to download multiple pictures and find that some are missing from the resulting zip archive, or you get the error message "No files available for download," your index may be incomplete or out of date (for example, after updating Starsky). A complete rescan of your library may solve the problem.

Wrong Search Results​

If search results are incorrect, for example, in the wrong order or not filtered properly:

It may be a bug if you cannot find any other reasons, such as a local configuration problem or a misunderstanding in how the software works. Please note that reports must be reproducible in order for us to provide a solution.

Broken Thumbnails​

If some pictures have broken or missing thumbnails, first check the logs. In case the application logs don't contain anything helpful:

  • The issue can be resolved by reloading the page or clearing the browser cache
  • You browse non-JPEG files in Library > Originals which have an icon but no preview
  • Your (virtual) server disk is full (add storage)
  • A disk usage or the inode limit has been reached (remove or increase it)
  • The storage folder is not writable or mounted read-only ( change permissions)
  • Files were deleted manually, for example to free up disk space
  • Files can't be opened, e.g. because the file system permissions have been changed
  • Files are stored on an unreliable device such as a USB flash drive or a shared network folder
  • Some thumbnails could not be created because you didn't configure at least 4 GB of swap
  • Your browser cannot communicate properly with the server, e.g. because a Reverse Proxy, VPN, or CDN is configured incorrectly (check its configuration and try without)
  • Your proxy, router, or firewall has a request rate limit, so some requests fail
  • There are other network problems caused by a firewall, router, or unstable connection
  • An ad blocker or other plugins block requests (disable them or add an exception)
  • You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

We also recommend checking your Docker Logs for messages like disk full, disk quota exceeded, no space left on device, read-only file system, error creating path, wrong permissions, and killed:

  • If a service has been "killed" or otherwise automatically terminated, this points to a memory problem
  • In case the logs show "disk full", "quota exceeded", or "no space left" errors, either the disk containing the storage folder is full (add storage) or a disk usage limit is configured (remove or increase it)
  • Errors such as "read-only file system", "error creating path", or "wrong permissions" indicate a filesystem permission problem

Depending on the cause of the problem, you may need to perform a full rescan once the issue is resolved.

Videos Don't Play​

If videos do not play and/or you only see a white/black area when you open a video:

  • You are using an incompatible browser, e.g. without AVC support (try another browser)
  • AVC support or related JavaScript features have been disabled in your browser (check the settings and try another browser)
  • An ad blocker or other plugins block requests (disable them or add an exception)
  • Your (virtual) server disk is full (add storage)
  • A disk usage or the inode limit has been reached (remove or increase it)
  • The storage folder is not writable or mounted read-only ( change permissions)
  • Files are stored on an unreliable device such as a USB flash drive or a shared network folder (check if the files are accessible)
  • Your browser cannot communicate properly with the server, e.g. because a Reverse Proxy, VPN, or CDN is configured incorrectly (check its configuration and try without)
  • There are other network problems caused by a proxy, firewall, or unstable connection (try a direct connection)
  • You are connected to the wrong server, VPN, CDN, or a DNS record has not been updated yet

We recommend that you check your Docker Logs and the browser console for messages related to HTTP requests, permissions, security, FFmpeg, videos, and file conversion.

Please note:

  1. Not all video and audio formats can be played with every browser. For example, AAC - the default audio codec for MPEG-4 AVC / H.264 - is supported natively in Chrome, Safari, and Edge, while it is only optionally supported by the OS in Firefox and Opera.
  2. HEVC/H.265 video files can have a .mp4 file extension too, which is often associated with AVC only. This is because MP4 is a container format, meaning that the actual video content may be compressed with H.264, H.265, or something else. The file extension doesn't really tell you anything other than that it's probably a video file.

!!! info "" We kindly ask you not to report bugs via GitHub Issues unless you are certain to have found a fully reproducible and previously unreported issue that must be fixed directly in the app. Ask for technical support if you need help, it could be a local configuration problem, or a misunderstanding in how the software works.

Used words​

*[AVC]: MPEG-4 / H.264 *[CDN]: Content Delivery Network *[VPN]: Virtual Private Network *[CPU]: Central Processing Unit *[DNS]: Domain Name System *[HTTP]: Hypertext Transfer Protocol *[SSD]: Solid-State Drive *[RAW]: image format that contains unprocessed sensor data *[URL]: Web Address *[FFmpeg]: transcodes video files *[HEVC]: High Efficiency Video Coding / H.265 *[SQLite]: self-contained, serverless SQL database *[swap]: substitute for physical memory *[host]: Computer, Cloud Server, or VM that runs Starsky *[read-only]: write protected *[filesystem]: contains your files and folders