EverShelf/docs/wiki/FAQ.md

❓ FAQ & Troubleshooting

---

Installation

The app shows a blank page after setup

• Open the browser console (F12 → Console) and check for errors
• Make sure PHP is running and api/index.php is reachable: visit https://your-server/dispensa/api/index.php?action=get_settings — it should return JSON
• Check your web server error log: tail -f /var/log/apache2/error.log

Camera doesn't work / barcode scanner won't open

Camera access requires HTTPS. On plain HTTP, browsers block getUserMedia().

• Set up HTTPS with Let's Encrypt, Caddy, or a self-signed certificate
• On Android, you can also add a security exception in Chrome: chrome://flags/#allow-insecure-localhost

"Permission denied" error for the data directory

chmod 755 data/
chown -R www-data:www-data data/

Docker container exits immediately

docker compose logs evershelf

Usually a permission issue on the mounted data/ volume. Try:

docker compose down
rm -rf data/
mkdir data/
docker compose up -d

---

AI Features

AI features don't work / "AI non disponibile"

1. Check that GEMINI_API_KEY is set in .env
2. Verify the key is valid at aistudio.google.com
3. Check that you haven't exceeded the free tier quota (15 req/min, 1500 req/day)
4. Look for errors in the PHP error log

Recipe generation stops midway

This is usually a Gemini API timeout. The app streams results via SSE — if the server PHP timeout is too low, the stream is cut short. Increase max_execution_time in php.ini:

max_execution_time = 120

---

Shopping List (Bring!)

"Bring! non configurato" message in the shopping tab

Add your Bring! credentials to .env:

BRING_EMAIL=your@email.com
BRING_PASSWORD=yourpassword

Items aren't syncing to Bring!

• Verify your credentials are correct by logging into getbring.com
• Check for rate-limit errors in the PHP error log — Bring! has API limits

---

Scale Integration

Scale readings don't appear in EverShelf

1. Confirm the gateway app is running and shows the WebSocket URL
2. Check the Gateway URL in EverShelf Settings matches exactly
3. Make sure both the Android device and the EverShelf server are on the same network
4. Look at the scale status indicator (⚖️) in the header — "disconnected" means no WebSocket connection

Scale shows weight but form doesn't auto-fill

• The auto-fill only triggers for products with unit g or ml
• Make sure you tapped "⚖️ Leggi bilancia" first to activate the scale modal
• The weight must stabilize (stay within 10g) for the countdown to start

Bluetooth scale not appearing in the gateway app

• Wake up the scale (step on it or press its button)
• Make sure Bluetooth and Location permissions are granted to the gateway app (Location is required by Android for BLE scanning)
• Restart the gateway app

---

Kiosk App

Setup wizard can't find my server

• Make sure the tablet is on the same Wi-Fi network as the server
• Try entering the URL manually instead of using auto-discovery
• Check that the server responds on the expected port (80/443/8080/8443)

Gateway install fails with an error dialog

The dialog shows the exact failure code. Common causes:

Code	Cause	Fix
STATUS_FAILURE (1)	Generic install failure — often OEM restriction	Enable "Install from unknown sources" for the kiosk app in Android Settings
STATUS_FAILURE_CONFLICT (3)	Signature mismatch with existing install	Uninstall the old gateway app, then retry
STATUS_FAILURE_STORAGE (6)	Not enough storage	Free up space on the device

Exit button (✕) is not visible

The ✕ button is injected into the header by the kiosk app. If the web app's header is covered or the page failed to load, try the hard refresh (↻) button. If neither is visible, triple-tap the page title area to access the developer settings.

App is stuck in kiosk mode after a crash

Restart the device. Screen pinning is released on reboot.

---

General

The version shown in the app is outdated

The version is cached by the browser. Do a hard refresh:

• Desktop: Ctrl+Shift+R / Cmd+Shift+R
• Android: tap the ↻ button (kiosk) or clear site data in Chrome settings

Transactions are missing from the log

The log shows the last 50 entries by default. Tap "Carica altri" to load more. Entries older than the database creation date won't appear.

"Can only undo transactions within 24 hours"

The undo window is 24 hours. For older operations, manually correct the inventory via the Edit function on the affected product.

Error reports keep creating duplicate GitHub issues

EverShelf uses a fingerprint to deduplicate — the same error from the same device won't create a new issue within 24 hours. If you're seeing duplicates, check the data/rate_limits/ folder and clear old files.

---

Getting Help

• Open an issue: github.com/dadaloop82/EverShelf/issues
• Email: evershelfproject@gmail.com
• Try the demo: evershelfproject.dadaloop.it/demo

When reporting a bug, include:

1. EverShelf version (shown in the header as v1.x.x)
2. Browser and OS
3. Steps to reproduce
4. Any error messages from the browser console (F12)