Skip to main content

Troubleshooting

Connection Issues​

The kiosk permanently shows "Offline"​

  1. Check the network connection of the machine (Wi-Fi or Ethernet)
  2. Verify the API URL in the setup — it must match your Stockaj instance
  3. Test the connection from the setup screen using the "Test Connection" button
  4. Verify that the Stockaj server is accessible from a browser on the same machine

"Failed ✗ — Unable to reach the server"​

Possible CauseCheck
Incorrect URLThe URL must end with /api/v2
Server downTest the URL in a browser
FirewallVerify the machine can access the *.stockaj.io domain
Network proxyConfigure the proxy at the operating system level

"Failed ✗ — Unknown error"​

This usually indicates an invalid or expired API token. Generate a new token from the Stockaj interface and update it in the configuration.

Scanning Issues​

The scanner doesn't detect anything​

See the QR / Barcode Scanner page for full diagnostics.

In summary:

  1. Verify the scanner is plugged in and in USB HID mode
  2. Test in a text editor — the code should appear as text
  3. Verify you are on the cockpit — the scanner is disabled on the setup page

"Unknown code" after a scan​

The scanned item does not exist in the Stockaj database. Check:

  • That the item is registered in Stockaj
  • That the QR code corresponds to the correct item
  • That the QR code is readable (not damaged or blurry)

Display Issues​

The application doesn't display in fullscreen​

The application is configured to start in fullscreen. If it doesn't:

  • Verify that tauri.conf.json has not been modified
  • On macOS, allow the application to enter fullscreen in System Preferences

The interface is too small / too large​

The interface is optimized for screens of at least 1280 × 720 px with a base size of 18 px. On very different resolutions, the display may not be optimal.

Data Issues​

Operations have been "pending" for a long time​

The yellow indicator "N pending operation(s)" means offline operations have not yet been synchronized.

  1. Check the network connection
  2. The kiosk automatically tries to sync every 5 seconds
  3. After 3 failures, an operation is marked as failed and will no longer be retried
caution

For persistent failed operations, contact the Stockaj administrator to verify the data on the server.

A confirmed checkout doesn't appear in Stockaj​

If the checkout was created offline, it will be synchronized once connectivity is restored. Check the connection indicator:

  • 🟡 Yellow = waiting for synchronization
  • 🟢 Green = all operations are synchronized

Access Issues​

I forgot the PIN code​

The PIN code is stored locally on the machine. To reset it:

  1. Close the application
  2. Delete the application's localStorage (key stockaj-kiosk-config)
  3. Relaunch the application — it will prompt for a new configuration
caution

This operation deletes the entire configuration (URL, token, PIN). You will need to re-enter it.

I'm stuck in kiosk mode​

Use the Ctrl+Shift+Q shortcut or the Escape key to display the exit dialog. If a PIN code is required and you've forgotten it, follow the procedure above.

Keyboard Shortcuts​

ShortcutAction
Ctrl+Shift+KEnter kiosk mode
Ctrl+Shift+QExit kiosk mode (PIN if configured)
EscapeExit kiosk mode (PIN if configured)
EnterConfirm selection / Close confirmation screen
SpaceClose confirmation screen
↑ ↓Navigate search results