Troubleshooting

Safe commands to see what is happening

Run these in the OpticWatch folder. None of them changes anything.

docker --version                       # is Docker installed?
docker compose version                 # is the Compose plugin installed?
docker compose ps                      # what is running, and is it healthy?
docker compose logs api                # the OpticWatch application log
docker compose logs --tail 100 api     # just the last 100 lines
docker compose logs init               # what happened on the first start

The application log never contains passwords, license keys or other credentials.

Docker problems

“docker” is not recognized, or command not found

Docker is not installed, or the terminal was opened before it was. On Windows and macOS, install Docker Desktop, then close and reopen PowerShell or Terminal. On Linux, install Docker Engine. See Install Docker.

“compose” is not a docker command

The Docker Compose plugin is missing. On Windows and macOS, update Docker Desktop. On Linux, install the docker-compose-plugin package from Docker's repository, as in Docker's guide for your distribution. OpticWatch needs docker compose with a space, not the older docker-compose program.

Cannot connect to the Docker daemon

On Windows and macOS, Docker Desktop is not running: start it and wait until it reports that the engine is running, then try again. On Linux, check that the Docker service is running with sudo systemctl status docker. If the message says permission denied, see Linux permissions.

“no configuration file provided”

The command was run outside the OpticWatch folder. Move into the folder that contains docker-compose.yml (with cd) and run it again.

OpticWatch does not start, or a service is unhealthy

Run docker compose ps. All of postgres, api and web should show (healthy). If one shows (unhealthy), or never gets past (health: starting):

• The first start is still downloading. Wait, then check again. The first start needs internet access to download the public images OpticWatch runs on.
• api is unhealthy or never becomes healthy: read docker compose logs api. A database created by a newer OpticWatch release is reported there; see Going back to an older release.
• The log says the encryption key does not match the stored credentials: the database is being used without the key that belongs to it, for example after restoring a database some other way. Nothing was changed. Restore with docker compose run --rm restore, which puts back the database and its key together.
• It worked before a restart of the computer: on Windows and macOS, make sure Docker Desktop is running. OpticWatch starts again by itself once Docker is up.
• You are on an Apple silicon Mac or another ARM device: OpticWatch 1.1.1 is an x86-64 build and has not been tested on ARM. If it does not start there, use an Intel or AMD computer. See ARM computers.

Cannot open OpticWatch in the browser

• Check that docker compose ps shows all three services healthy, and that the web line lists port 38080.
• On the OpticWatch computer itself, use http://localhost:38080. Note http, not https: OpticWatch itself serves plain HTTP.
• From another computer, use http://SERVER-IP:38080 with the OpticWatch computer's network address. If it works locally but not from elsewhere, a firewall on the OpticWatch computer or on the network is blocking port 38080. Allow it for your local network only.
• If saving anything fails with “Request origin is not allowed”, a reverse proxy in front of OpticWatch is not passing the Host header through. Fix the proxy, or see APP_URL in the release README.md.

Port 38080 is already in use

If docker compose up -d reports that port 38080 is already allocated, another program is using it. You can publish OpticWatch on a different port instead, for example 38180 (any free port works):

In the OpticWatch folder, add the line to a file named .env, which this creates if it does not exist. In PowerShell:

Add-Content -Path .env -Value "WEB_PORT=38180"

In Terminal on macOS or Linux:

echo "WEB_PORT=38180" >> .env

Then apply it with docker compose up -d. If the file already has a line for the same setting, edit that line instead of adding a second one.

Then open OpticWatch on that port, for example http://localhost:38180. Keep the .env file when you update.

Camera problems

The camera's page shows why its last check failed. The full list of reasons and fixes is in RTSP addresses; the most common are below.

“The camera could not be reached” or “refused the connection”

The OpticWatch computer cannot reach the camera's RTSP port. Check the IP address and port, that the camera is on and connected, and that no firewall or VLAN separates the camera network from the OpticWatch computer. Test from OpticWatch itself:

docker compose exec api ffprobe -rtsp_transport tcp -i 'rtsp://username:[email protected]:554/stream-path'

“The RTSP server rejected the supplied credentials”

The username or password in the RTSP address is wrong, or contains characters such as @ or : that must be encoded (@ as %40). See Passwords with special characters. Some cameras also lock an account after repeated failures; check the camera's own settings.

“Did not provide a usable video stream” or an RTSP error

The camera answers but the stream path is wrong for this model. Check the path in the camera's manual, or use ONVIF setup to find it.

Camera not found by an ONVIF scan, or ONVIF cannot connect

A network scan finding nothing is expected inside Docker's default network, and OpticWatch does not search for cameras on its own: a camera not found by a scan can still be added by typing its address. If connecting fails, check the ONVIF port, that ONVIF is enabled on the camera, and the ONVIF username and password. See ONVIF setup.

A camera is never checked

• Its monitoring is Paused: open the camera and choose Resume monitoring.
• It shows Paused — plan limit: the installation holds more cameras or sites than its edition allows, or a paid installation has no valid license. See Paused by the plan limit.

Cameras are checked less often than their interval

A camera's last check is normally a few seconds older than its interval: the interval counts from the end of one check, and the check itself takes a few seconds. If last checks fall well behind that:

• Many cameras are not answering, for example a whole site is offline. Each one holds a check for its full probe timeout, so the others wait. Fix the cameras or the network, or if many cameras are often unreachable, raise MONITOR_WORKERS; see Large installations.
• The server is too small for the number of cameras, so each check takes longer. Compare it with Server size; higher-resolution or H.265 streams and slow links need more.
• An earlier release's MONITOR_WORKERS is still set in a .env file, for example 8. Your value takes precedence over the default of 32; remove the line to use the default.

A camera shows Offline but seems to work

Open the camera and read the latest failure reason. The camera may be reachable from your own computer but not from the OpticWatch computer, or may be slow to start a stream: try raising its Probe timeout. Use Check now to test after each change. To react less to brief drops, raise the offline threshold in Settings, Monitoring.

License problems

• “Could not reach the licensing service”: the server needs outbound HTTPS to cloud.opticwatch.dev to activate or deactivate. Nothing changed locally.
• “Every deployment is already activated”: deactivate the license on another installation first, or contact support if that server was lost.
• A paid installation shows Free: the License screen says why. Your data and cameras are unaffected.

More in Editions and licenses.

Contacting support

Email [email protected] with what you tried and what you saw. It helps to include the output of these commands, run in the OpticWatch folder:

cat VERSION
docker compose ps
docker compose logs --since 24h api > opticwatch-api.log

Attach the opticwatch-api.log file this creates. Do not send a backup file: it contains your encryption key.