Common Issues

API Won’t Start

Symptom: ./ScanPick.Api exits immediately with no output.

Cause: Missing required environment variables.

Fix: Ensure DATABASE_CONNECTION_STRING and JWT_SECRET are set:

export DATABASE_CONNECTION_STRING="Host=localhost;Database=scanpick;Username=scanpick;Password=..."
export JWT_SECRET="your-64-char-secret"
./ScanPick.Api

Database Connection Failed

Symptom: Failed to connect to PostgreSQL on startup.

Causes and fixes:

Cause	Fix
PostgreSQL not running	docker compose up -d postgres or systemctl start postgresql
Wrong connection string	Check DATABASE_CONNECTION_STRING format
Database doesn’t exist	CREATE DATABASE scanpick OWNER scanpick;
Firewall blocking	Ensure port 5432 is accessible from the API host
SSL mismatch	Add SSL Mode=Disable for local connections, or SSL Mode=Require for remote

Dashboard Shows White Page

Symptom: Web dashboard loads but displays a blank white page.

Cause: JavaScript error — often due to missing API or wrong base URL.

Fix:

1. Open browser dev tools (F12) and check the Console tab for errors
2. Ensure the API is running on the expected port
3. Clear browser cache and reload

Mobile App Can’t Connect

Symptom: Mobile app shows “Connection error” or “Unable to reach server”.

Causes and fixes:

Cause	Fix
Wrong API URL in app config	Check API_BASE_URL in mobile/.env
Firewall blocking	Ensure port 5000 is accessible on the warehouse WiFi
Server not running	Try opening the dashboard at http://localhost:5000
WiFi network isolation	Check that mobile devices can reach the server IP

License Validation Failed

Symptom: API refuses to start with “Invalid license key”.

Causes and fixes:

Cause	Fix
Expired license	Renew through scanpick.cc/account
Wrong key entered	Check the key from your purchase email
Keygen API unreachable	The API caches validation for 24 hours — check outbound internet access
License not activated	Contact support

Disk Space

Symptom: API logs database errors or refuses writes.

Fix: Check disk space and prune old data:

df -h
# Free space if needed
docker system prune
# For PostgreSQL WAL logs
docker compose exec postgres psql -U scanpick -c "CHECKPOINT;"

Logs

For more detailed troubleshooting, see the Logs guide. If the issue persists, open a GitHub issue.