Skip to content

Troubleshooting

Container Issues

Container won't start

Check logs: 

docker logs stash-sense

Common causes:

  • Missing database files - ensure /data contains the .voy files
  • GPU driver issues - try without GPU first to isolate
  • Port conflict - change from 6960 to another port

"Database not loaded"

The face recognition database hasn't been downloaded yet. This is normal on first startup.

Fix: Navigate to /plugins/stash-sense in Stash, go to the Settings tab, and click Update in the Database section to download the database.

Alternatively, verify the volume mount has database files:

docker exec stash-sense ls -la /data

Should show face_facenet.voy, face_arcface.voy, performers.json, manifest.json. If empty, either download via the Settings UI or check your volume mount path.

"Load model from /app/models/facenet512.onnx failed: File doesn't exist"

The ONNX face recognition models are not bundled in the Docker image — they need to be downloaded after first startup.

Fix: Navigate to /plugins/stash-sense in Stash, go to the Settings tab, and click Download All in the Models section. This downloads FaceNet512 (~90 MB) and ArcFace (~130 MB) to /data/models/.

Alternatively, download via the API:

curl -X POST http://localhost:6960/models/download-all

Health check shows "degraded"

This is expected on first startup before the database and models are downloaded. Once you download both from the Settings tab, the status will change to "healthy" after the first identification request.

Health check failing

# Test manually
curl http://localhost:6960/health

# Check container status
docker ps -a | grep stash-sense

If container is restarting, check logs for the error.

GPU Issues

"CUDA not available"

The container fell back to CPU mode.

Verify GPU is accessible: 

docker exec stash-sense nvidia-smi

If this fails:

  1. Ensure nvidia-container-toolkit is installed
  2. Container needs --runtime=nvidia --gpus all
  3. Restart Docker daemon after toolkit install

"CUDA out of memory"

GPU memory exhausted. Check what's using it:

nvidia-smi

Solutions: - Stop other GPU-using containers temporarily - Use CPU mode (slower but works)

Slow performance on GPU

If GPU is detected but still slow:

  1. Check GPU utilization during requests: watch nvidia-smi
  2. Ensure models aren't being re-downloaded (mount model cache volume)
  3. First request is slow (model loading) - subsequent requests should be faster

Connection Issues

Plugin can't reach sidecar

From Stash container, test connectivity: 

docker exec stash curl http://stash-sense-host:6960/health

Common fixes:

  • Use host IP if containers are on different Docker networks
  • Check firewall isn't blocking port 6960
  • Verify the Sidecar URL in plugin settings matches your container's host and port

Sidecar can't reach Stash

Test from sidecar: 

docker exec stash-sense curl http://your-stash-host:9999/graphql

Common fixes:

  • Verify STASH_URL environment variable is correct
  • Verify STASH_API_KEY is valid
  • Check Stash is running and accessible
  • Don't use localhost in STASH_URL — it refers to the container itself, not the host. Use the host's LAN IP.

Windows: "Connection refused" on localhost

On recent Docker Desktop versions, localhost may resolve to ::1 (IPv6) instead of 127.0.0.1. Try:

  • Use http://127.0.0.1:6960 instead of http://localhost:6960
  • Use the machine's LAN IP (e.g., http://192.168.1.100:6960)

See the Windows / WSL section of the installation guide for more details.

Plugin Issues

Plugin Python dependencies

The plugin backend requires the requests library in Stash's Python environment.

Symptoms: Plugin appears installed but all sidecar requests fail silently. Stash logs may show ModuleNotFoundError: No module named 'requests'.

Fix: Install requests in Stash's Python environment:

# If Stash runs in Docker:
docker exec stash pip install requests

# If Stash runs natively:
pip install requests

Plugin backend not working

Check Stash logs for Python errors:

docker logs stash 2>&1 | grep -i "stash.sense\|error\|traceback"

Common causes:

  • Plugin files not installed correctly — reinstall from the plugin source
  • Python not available in Stash's environment
  • Sidecar URL not configured in plugin settings

Plugin not appearing

  1. Check plugin files are in the correct location
  2. Reload plugins in Stash settings
  3. Check Stash logs for errors

Stash-Box Endpoint Issues

Credentials not detected

The sidecar reads Stash-Box endpoint credentials from Stash's Settings > Metadata Providers at startup. If endpoints aren't showing up:

  1. Verify the endpoint is configured in Stash's Metadata Providers
  2. Restart the sidecar, or use the Refresh button in the plugin's Settings tab
  3. Check sidecar logs for errors during endpoint discovery

Endpoint not available for upstream sync

Make sure the endpoint is enabled in the plugin's Settings tab. Disabled endpoints are skipped during analysis but their configuration is preserved.

Recognition Issues

No faces detected

  • No sprite sheets: Generate sprite sheets first (Settings > Tasks > Generate > Sprites)
  • Low quality sprites: Regenerate with higher quality settings
  • No clear face shots: Some scenes don't have good face visibility
  • Very small faces: Detection has a minimum size threshold

Wrong matches

  • High distance score: Scores above 0.5 are less reliable
  • Similar looking performers: Some faces are genuinely similar
  • Database coverage: The performer may not be in the database or may have poor reference images

Performer matched but not in library

This is expected — the face matched a performer in the database who you haven't added to your Stash yet. Options:

  1. Click "View on Stash-Box" to verify the match
  2. Add the performer to your Stash manually
  3. Use Stash's "Identify" feature to import from a Stash-Box endpoint

Database Issues

Corrupt database files

If you see index errors or crashes on load:

# Remove and re-download via Settings UI, or manually:
rm -rf /path/to/data/*.voy /path/to/data/performers.db /path/to/data/*.json
# Then download fresh via Settings tab > Database > Update

Outdated database

Check current version: 

curl http://localhost:6960/database/info

Compare with the latest release on GitHub. New databases include more performers and improved embeddings.

Getting Help

If you're stuck:

  1. Check container logs: docker logs stash-sense
  2. Test health endpoint: curl http://localhost:6960/health
  3. Verify database files exist and have correct permissions
  4. Open an issue on GitHub with:
  5. Container logs
  6. Health endpoint response
  7. Docker/Unraid version
  8. GPU model (if applicable)