> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laportenard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and their fixes.

## Orders do not persist after navigation or reload (dev mode)

### Symptoms

Running in development mode (`npm run dev`) with mock bootstrap data. Adding items to an order, navigating away, or refreshing causes the order to appear lost — even though Dexie persistence is enabled.

### Root cause

React StrictMode in development performs a mount → unmount → remount cycle. The POS restore effect used a mount-guard ref that was not reset on cleanup. On remount, restore was skipped and persisted state was not loaded back into the UI.

### Fix

In `src/features/sales/hooks/usePOS.tsx`, reset the restore-guard ref in the effect cleanup:

```typescript theme={null}
useEffect(() => {
  // ... restore logic ...
  return () => {
    restoreAttemptedRef.current = false; // Allow remount to restore
  };
}, []);
```

### Verify

1. Start the dev server: `npm run dev`
2. Open a table and add at least one item
3. Navigate back to the floor plan and return to the same table (or refresh `/order`)
4. Confirm the order is restored

***

## Hub won't start: cannot find module '@nu/sync-protocol'

Build the protocol package first:

```bash theme={null}
cd nu_pos_sync_protocol
npm run build
```

***

## Auth fails for all terminals

Make sure Odoo is running and credentials in `nu_pos_hub/.env` are correct. In local development, ensure `HUB_DEV_AUTH=true` is set in the hub's `.env` file.

***

## Frontend stuck in "Connecting" state

1. Is the hub running? `curl http://localhost:8766/health`
2. Is `nu_hub_enabled` set to `true` in bootstrap config?
3. Check browser DevTools Network tab for WebSocket connection attempts
4. Look for connection errors in the browser console

***

## Orders not forwarding to Odoo

```bash theme={null}
pos-hub stats
# "Pending Forward: 15" that never decreases
```

1. Is Odoo reachable from the hub? `curl http://localhost:8069/web/login`
2. Check hub logs for forwarding errors: `journalctl -u pos-hub -f`
3. The hub authenticates as `ODOO_USER`/`ODOO_PASSWORD` — ensure this user has POS access

***

## Customer RNC validation fails

* Check internet connection (DGII requires external access)
* Verify the DGII module is installed on Odoo
* Personal cédulas may not be in the DGII registry — this is expected behavior

***

## Android tablet not connecting to hub

### Symptoms

The Android app logs in to Odoo successfully but never connects to the hub WebSocket. The sync status indicator stays disconnected. No connection attempts appear in hub logs.

### Root cause

Android WebView enforces CSP strictly. Scheme-specific wildcards (`ws://*`, `wss://*`) in `connect-src` do not match IP addresses on Android. Additionally, Android 9+ blocks cleartext (`ws://`) traffic by default.

### Fix

1. Use bare `*` in `connect-src` in `src-tauri/tauri.conf.json`:
   ```
   connect-src 'self' https://ipc.localhost *
   ```

2. Set `usesCleartextTraffic` to `"true"` in the `defaultConfig` block of `src-tauri/gen/android/app/build.gradle.kts`

3. Rebuild and reinstall the APK

### Verify

1. Check hub logs for a WebSocket connection from the tablet's device ID
2. Confirm the sync status indicator shows connected
3. Create an order on the tablet and verify it appears on other terminals

See [Tauri Android](/guides/tauri-android) for full details.

***

## Stale dev.sqlite causing SQLite errors

```bash theme={null}
rm nu_pos_hub/dev.sqlite
# Restart the hub — it recreates the schema
```