Common problems

Start with the status page: open /status on your server, for example http://192.168.1.10:8080/status. It needs no sign-in and says in plain words which part isn’t working. After that, Settings → Server → Logs usually has the details. See Logs, status and repairs.

I can’t open the server on port 8080

Check that it’s running.

Docker: in the folder with your Compose file, run docker compose ps. Both credenza and postgres should be running. docker compose logs credenza shows why the server stopped, if it did. The server waits for the database to report healthy before it starts.
Linux package: installing the package doesn’t start the server. It starts after you run sudo credenza-setup, which sets up the database. Then check systemctl status credenza, and journalctl -u credenza for its log.

Check the address.

From another device, use the server machine’s network address, such as http://192.168.1.10:8080. localhost only works on the server machine itself.
The Docker Compose file publishes port 8080. If you changed the left-hand side of "8080:8080", use that port instead.
The Linux package listens on 0.0.0.0:8080, set in /etc/credenza/credenza.env. Restart the service after changing it.
A firewall on the server machine may be blocking the port.

With Behind a reverse proxy ticked, the sign-in cookie is marked as HTTPS-only. If you actually reach the server over plain http://, your browser refuses to keep the cookie, so every sign-in appears to fail.

To get back in, set this environment variable on the server and restart it:

MediaServer__ReverseProxy__ForceDisable=true

That overrides the saved setting. Sign in, untick Behind a reverse proxy under Settings → Server → General, then remove the variable and restart again. For where environment variables go, see Configuration.

The set-up wizard appears on a server you already set up

Credenza sends everyone to Set up your server only when its database has no accounts at all. So if the wizard appears again, the server is connected to an empty database, not the one you set up. The status page’s User account row confirms it: No user account exists yet.

Usual causes:

Docker: the Compose file keeps the database in ./data/postgres, relative to the folder you run docker compose from. Running it from a different folder, or moving or deleting that folder, starts a new, empty database.
The database connection string changed, so it now points at a different database or server.

Don’t finish the wizard on the empty database. Put the old data folder or connection string back and restart. Your media files are untouched either way, and so is the database you set up, as long as it still exists.

A library won’t save, or a scan finds nothing

The folder has to be a path the server can see. When you add a library, you give a path as the server sees it, which isn’t always the same as on your computer:

In Docker, it’s the path inside the container. The Compose file mounts your media at the same path on both sides (/srv/media:/srv/media) so the two match. If you mounted it somewhere else inside the container, use that path.
Select Browse… next to a folder field to see the server’s own folders and pick from them. If your media isn’t there, the server can’t see it.

Saving a library checks each folder. Path ‘…’ does not exist. means the server can’t find that folder at all. Path ‘…’ could not be read means it exists but the server isn’t allowed to open it.

The server needs permission to read your files.

Docker: both containers run as the PUID and PGID in your .env file. These must be an account that can read your media, usually the account that owns it.
Linux package: the service runs as the credenza user. Add it to the group that owns your media, for example sudo usermod -aG media credenza, then sudo systemctl restart credenza.
To keep match files next to your media, the server also needs write access there.

If some folders are unreadable, the scan skips them and logs Skipping unreadable directory with the path. Search the log for unreadable to find them.

Other things to check:

Nothing is playable until a scan finishes. Go to Settings → Server → Libraries and select Scan now on the library’s row.
If nothing ever scans, look at the status page’s Background work row. Scans run as queued jobs, and if the queues couldn’t be set up, nothing is ever scanned. The row says why.
Files named in a way the scanner can’t read won’t be found. See Naming films and Naming shows and anime.

Films and shows have no artwork, or everything is unmatched

Films, shows and anime get their titles, artwork and synopses from TMDB, which needs a TMDB read access token under Settings → Server → Metadata. The status page’s Metadata row says what’s wrong:

Metadata row says	What to do
films and shows have no artwork or synopses until a TMDB read access token is added	Add the token under Settings → Server → Metadata
TMDB rejected the read access token	The token is wrong or has been revoked. Paste it again. TMDB offers an API key and a read access token, and Credenza needs the read access token
TMDB is rate limiting this server or Could not reach TMDB	Wait and try again, or check the server’s internet connection and any outbound proxy under Settings → Server → Metadata
games have no box art until … credentials are added	Add ScreenScraper or Twitch (IGDB) credentials for your games libraries

Once the token works, titles still in Needs matching can be fixed there. See Fixing matches and How matching works.

A video won’t play

When the server can’t start a video, the player shows the reason. The common ones:

Message	Cause and fix
“Title” has no media files.	Nothing on disk is linked to this item. Rescan the library
Every file for “Title” is missing from disk. / The file for this movie is no longer on disk.	The file was moved, renamed or deleted, or the drive it’s on isn’t connected. Reconnect it or put the file back, then rescan
Could not start ffmpeg: … or ffprobe not found (…)	The server can’t find ffmpeg, which it needs to play anything. See ffmpeg is missing or incomplete
Maximum concurrent streaming sessions reached (2/2 active). Stop an existing session before starting another.	Too many videos are playing at once. Stop one, or raise Concurrent streams under Settings → Server → Transcoding. Closing a tab doesn’t tell the server, so an abandoned stream keeps its place until the Idle timeout on the same page stops it
Streaming unavailable (…)	The server returned an error without a reason. Check Settings → Server → Logs at the time you pressed play

ffmpeg is missing or incomplete

Credenza uses ffmpeg and ffprobe to read and play every video. The Docker image includes both. The Linux packages use your system’s.

To see what the server found, sign in and open /api/ffmpeg on your server, for example http://192.168.1.10:8080/api/ffmpeg. It shows whether ffmpeg is available, its version, the path it tried and, if it failed, the reason.

If ffmpeg is installed somewhere the server doesn’t look, enter the full paths under Settings → Server → General, in ffmpeg path and ffprobe path. Leave both blank to use whichever ffmpeg is on the server’s PATH.

Fedora’s ffmpeg can’t transcode H.264

Fedora’s own ffmpeg-free package has no H.264 software encoder. Credenza installs with it, but any video that needs transcoding won’t play. Replace it with the full ffmpeg from RPM Fusion:

sudo dnf swap ffmpeg-free ffmpeg --allowerasing

RHEL, Rocky and Alma ship no ffmpeg at all. Enable EPEL and RPM Fusion before you install Credenza. See Installation.

The graphics card isn’t being used

Go to Settings → Server → Transcoding. It shows which encoder the server is currently using. Each hardware encoder is listed as available, or unavailable with the reason. The server tests each encoder with a short trial encode, so the reason tells you what actually failed on your machine.

The usual causes:

The video encoder is set to Software only. Choose Hardware when available.
Docker wasn’t given the GPU. A plain Compose file doesn’t pass the graphics card into the container, so the server uses the CPU. Add the GPU override file for your card from Installation, then run docker compose up -d again.
Docker on a Mac can’t use the GPU at all, and Docker on Windows can only use NVIDIA cards.
Linux package: install your card’s driver (NVIDIA’s driver, or a VA-API driver for AMD and Intel). The credenza user must be in the video and render groups. The installer adds it where those groups exist.
A graphics card may only encode a limited number of streams at once. The Transcoding page shows that limit, and streams beyond it are encoded on the CPU.

A change of encoder applies to the next video you start. For the full setup, see Hardware acceleration.

Apps and devices

The Android app won’t connect. The app explains why under the address field. See Connect to your server for what each message means.
The TV’s sign-in code won’t open on my phone. The QR code holds the address the TV uses, so your phone must be able to reach that address, which usually means being on the same network. Or type the code at <your server>/link on a computer instead. See Sign in from another device.
There’s no Install app… in the account menu. Chrome and Edge only offer to install over HTTPS, Firefox can’t install web apps, and Android uses the native app instead. See Install it as an app.

Getting help

If none of this fixes it, ask in the Credenza Discord, or email hello@credenza.tv. Say which version you run, from Settings → User → About, and attach a log export. What to send when you ask for help explains how to make one.