Skip to content

FaceStream.AI

Documentation

Help

Troubleshooting

Cameras without a picture, people not recognised, messages that do not arrive, wrong times, a forgotten password — and where to look first.

On this page

The most common questions, sorted by where they show up. Most answers are already on the screen: the camera cards on the Overview, the visit list under Events, and the answers of the receivers under Notifications → Recent deliveries.

A camera shows no picture

What you see What to check
No picture on the camera card The Stream URL, and the username and password in their own fields rather than in the address. Try the address in VLC or a browser from the same network
Last picture: no live frames The stream stopped delivering: the camera rebooted, lost its network, or dropped the connection. FaceStream.AI reconnects by itself
The picture comes and goes Many cameras serve only two or three streams at a time. Close other viewers, or give FaceStream.AI the sub stream
The camera search finds nothing Open FaceStream.AI by its IP address, not by localhost. ONVIF may be switched off on the camera, or the camera sits in another network, see When a camera is not listed
The camera refused the sign-in Username or password, on Hikvision and some others, ONVIF has a user of its own, see When sign-in fails

Somebody is not recognised, or recognised wrongly

What you see What to try
A family member arrives as Unknown Add two or three more photos, ideally from that camera's angle, see People and photos
Faces far from the camera are not found Detail High in the camera's Recognition dialog, or a larger Output size. Both cost processing time
Two people get mixed up Strictness Strict, and check that no photo shows the wrong person or two faces
Recognition is slow to react A lower Check every … frames, or On request only with a trigger
A real person is reported as a suspected spoof Backlight and screens behind the person confuse the liveness check. Lower Confidence needed a little, or turn the camera away from the light
Somebody in the log, but no message See the next section

Recognition and requests explains every setting.

Messages do not arrive

Look at Notifications → Recent deliveries first.

No entry at all means no rule matched. Check the rule:

  • The event. At a camera set to On request only, a stranger is a Face without a match, never a Visit starts, see Which event for which question.
  • Who, cameras, times and days. A rule with Selected people ignores everybody else; with cameras ticked, it ignores the others; outside Between and On it is silent.
  • Report. After Then pause or Once per time window, the same person stays quiet for a while, and for this, everybody Unknown counts as one person.
  • Only when the liveness check passed keeps a rule silent if the camera does not run the check.
  • A request that recognised somebody does not also report the Unknown next to them.
  • Saved? Changes take effect with Save connections and rules.

An entry marked failed has the reason in the answer: 401 Client Error: Unauthorized , a wrong user or password; timed out, nothing answered at that address; not connected to the broker, the MQTT broker could not be reached. Test on the connection sends a message straight away, so you can try again after each change.

Delivered, but nothing happens means the receiver got it and did nothing with it: the text input in Loxone Config has a different name, the automation in Home Assistant compares a different value. What was sent shows the exact text.

Times in messages are wrong

Usually by one or two hours: the container runs in UTC. Start it with your time zone: -e TZ=Europe/Berlin, or TZ under environment in Compose and on a NAS. The note at the top of Notifications says which zone is in use. See Installation.

They point to the address the interface was last opened under. Open it once by an address the receiver can reach, http://192.168.1.20:8000, not http://localhost:8000, and new messages carry the right links. A phone away from home needs a VPN to reach them.

Home Assistant and Loxone

FaceStream.AI is slow, or the machine is busy

Recognition runs on the processor. What costs the most, roughly in this order:

  • The liveness check, Effort Fast instead of Thorough halves that part
  • Cameras recognising continuously, On request only for a door, or a higher Check every … frames for the others
  • Large frames and high Detail, a smaller Output size; 1280×720 is plenty for most doors
  • Many faces at once, a busy entrance costs more than a quiet door; zones leave out the parts where nobody needs recognising

The system requirements say how much hardware each edition needs.

Forgotten password

The password can only be reset on the machine itself, anyone who reaches the sign-in page over the network must not be able to. Recognition keeps running, and cameras, people, visits and the licence are not touched. Anyone still signed in is signed out, and the next visit to the interface asks for a new password.

Docker, including NAS systems:

docker exec facestream /FaceStream.ai/facestream --reset-password

Replace facestream with the name of your container, docker ps lists them. On a Synology or QNAP, open a terminal for the container in the container manager and run /FaceStream.ai/facestream --reset-password there.

Linux without Docker:

sudo -u facestream env DATA_FOLDER=/var/lib/facestream /opt/facestream/facestream --reset-password

If you cannot run a command, delete the file auth.json in the data folder, /data in a container, /var/lib/facestream without Docker. It has the same effect. Everything else in that folder must stay.

Asking for help

When you contact support, include the version, at the bottom left of the interface, and what you saw. The log helps most:

docker logs --tail 200 facestream
journalctl -u facestream-video -u facestream-frontend -n 200

The first line is for Docker, the second for Linux without Docker. The log contains no passwords, tokens or pictures, but it does contain names and addresses: read it before you send it.