Troubleshooting
import { Aside } from ‘@astrojs/starlight/components’;
make demo fails to start
Section titled “make demo fails to start”Docker is not running
Section titled “Docker is not running”Cannot connect to the Docker daemonStart Docker Desktop (macOS/Windows) or sudo systemctl start docker (Linux).
Port 8080 is already in use
Section titled “Port 8080 is already in use”Bind for 0.0.0.0:8080 failed: port is already allocatedStop whatever is using port 8080 (lsof -i :8080), or override the port:
UFME_SERVER_PORT=9090 make demoDocker build fails on Apple Silicon
Section titled “Docker build fails on Apple Silicon”If the Rust shard container fails to build on M1/M2/M3 Macs, ensure Docker Desktop has “Use Rosetta for x86_64/amd64 emulation” disabled (Settings > General). The containers build natively for arm64.
Model download times out
Section titled “Model download times out”The first run downloads ~700 MB. On slow connections, download models separately first:
make models # download models onlymake demo # then start the stackAPI returns errors
Section titled “API returns errors”400: “No face detected”
Section titled “400: “No face detected””The image contains no face, or the face is too small / blurred / angled for the detector. Try a front-facing photo where the face occupies at least 20% of the image area.
422: “Quality gate rejected”
Section titled “422: “Quality gate rejected””The face did not meet the minimum quality threshold. Common causes: blur, occlusion (sunglasses, masks), extreme lighting, very low resolution.
To temporarily lower the threshold for testing:
UFME_THRESHOLD_QUALITY=0.25 make demo451: “PAD gate rejected”
Section titled “451: “PAD gate rejected””The PAD model classified the image as a spoof (printed photo, screen replay, mask). If you are testing with a photograph of a photograph, this is expected behaviour.
Search returns empty candidates
Section titled “Search returns empty candidates”- Check the gallery is populated:
curl http://localhost:8080/api/v1/gallery - Verify you are querying the correct partition
- Lower the similarity threshold:
"threshold": 0.3in the metadata - Ensure the probe image contains the same person as an enrolled template
Local development
Section titled “Local development”make install fails
Section titled “make install fails”Ensure Python 3.12+ and uv are installed:
python3 --version # must be 3.12+uv --version # https://docs.astral.sh/uv/Rust build fails
Section titled “Rust build fails”error: could not find `faiss` via pkg-configInstall FAISS headers: brew install faiss (macOS) or build from source (Linux). If you only need the Python pipeline, skip Rust entirely — unit tests do not require it.
Tests fail with ModuleNotFoundError
Section titled “Tests fail with ModuleNotFoundError”make install # re-sync all dependencies.venv/bin/pytest tests/unit/ -xDocker and deployment
Section titled “Docker and deployment”Shard containers restarting
Section titled “Shard containers restarting”Check logs: docker compose -f deploy/docker/docker-compose.demo.yml logs shard-0
Common causes: FAISS library missing (build issue), insufficient memory (each shard needs ~1 GB for demo), or the data volume is not writable.
Container runs out of memory
Section titled “Container runs out of memory”Each shard needs roughly gallery_size * 64 bytes of RAM for the PQ index. A 10M gallery needs ~1 GB per shard; 200M needs ~15 GB per shard. Increase Docker’s memory in Docker Desktop > Settings > Resources.