Troubleshooting

This page covers solutions for common issues organized by category.

Connection Issues

Client cannot find the server

Symptoms: Client shows "Searching for server" or "No server found."

Solutions:

1. Verify HandyCafe Server is running on the management PC.
2. Confirm both PCs are on the same subnet (e.g., both on 192.168.1.x).
3. Check that mDNS is not blocked by your network switch or router.
4. Try manual connection: enter the server's IP address directly in the client settings.
5. Verify no other software is using the server's TCP port (default: 5001).

Client connects and then disconnects immediately

Symptoms: Client briefly shows "Connected" then drops back to "Searching."

Solutions:

1. Verify the connection key matches on both server and client. The key is set in Settings > Network on the server.
2. Check for network instability (packet loss, cable issues).
3. Ensure the server has not reached its license PC limit.
4. Review server logs for authentication failure messages.

Client shows "Offline" on the server but the PC is running

Symptoms: The client PC is powered on and the client application is running but the server shows it as offline.

Solutions:

1. On the client PC, verify HandyCafe Client is actually running (check system tray).
2. Check the network connection on the client PC (can it ping the server?).
3. Verify firewall rules: TCP ports 5001-5003 must be open on both server and client.
4. Restart HandyCafe Client on the affected PC.
5. If using VLANs, ensure the server and client VLANs can communicate.

Cannot connect after changing network settings

Symptoms: After changing ports or connection key, clients cannot connect.

Solutions:

1. Ensure clients are updated with the new port numbers and connection key.
2. Restart the HandyCafe Server after changing network settings.
3. Update firewall rules to allow the new ports.
4. All clients must be reconfigured with the new values.

Session Problems

Cannot start a session on a client

Symptoms: Start button is disabled or start action fails with an error.

Solutions:

1. Check license status. If in read-only mode, new sessions cannot start.
2. Verify the client status is "Idle". Sessions can only start on idle clients.
3. Check cashier permissions. The role must have AUTH_CLIENT_LOGIN permission.
4. Ensure pricing is configured (Settings > Pricing must have a valid hourly rate).

Session timer shows incorrect time

Symptoms: The displayed time does not match the actual elapsed time.

Solutions:

1. Check the system clocks on both server and client PCs. They should be synchronized (use NTP).
2. If the session was paused, the paused duration is not counted.
3. For prepaid sessions, the timer shows remaining time, not elapsed time.

Session cost seems wrong

Symptoms: The amount charged does not match expectations.

Solutions:

1. Check the pricing schedule. If enabled, the session may have passed through multiple pricing slots with different multipliers.
2. Review pricing settings: base hourly rate, VAT, startup fee, rounding.
3. Check the session's pricing segments in the transaction details for a breakdown.
4. Verify the payment method's commission and fixed fees.
5. For prepaid sessions, check whether "Lock at Purchase" or "Live Schedule" mode is active.

Paused session cannot be resumed

Symptoms: Resume action fails or is not available.

Solutions:

1. Verify the client PC is still connected to the server.
2. Check that the client status shows "Paused" (orange).
3. If the client disconnected during pause, it may need to reconnect first.

Payment Issues

Payment method is missing from the dropdown

Symptoms: Expected payment method does not appear when closing a session or order.

Solutions:

1. Verify the payment method exists in Management > Payment Methods.
2. Check that the payment method is active (not deleted or disabled).
3. Check cashier permissions. PAYMENT_MANAGE must be granted to see all methods.

Commission calculation seems incorrect

Symptoms: The deducted commission does not match the expected rate.

Solutions:

1. Verify the payment method's commission rate (as a percentage) and fixed fee.
2. Commission formula: commission = (amount charged * commission rate / 100) + fixed fee.
3. Check if the cashier applied a manual override to the amount charged.

Client Display Issues

Client idle screen is blank

Symptoms: The idle screen shows nothing instead of the configured slideshow.

Solutions:

1. Verify that idle screen is enabled in Settings > Clients > Idle Screen.
2. Check that at least one media item (image or video) has been added.
3. Verify the media files are valid and not corrupted.
4. Trigger a sync to push the latest settings to the client.

Client menu does not show apps

Symptoms: The app launcher is empty or missing categories.

Solutions:

1. Verify apps and categories are configured in Settings > Clients > Content.
2. Check that categories and apps have visibility toggled on.
3. Verify the client has received the latest menu data (changes push automatically via TCP).
4. Restart the client if real-time sync did not apply.

Client appearance theme is not applied

Symptoms: The client shows default appearance instead of configured theme.

Solutions:

1. Verify theme settings are saved in Settings > Clients > Appearance.
2. Trigger a settings push to clients.
3. Restart the client application.

Remote Desktop Issues

Remote desktop is laggy or choppy

Symptoms: Video feed is delayed, stuttering, or has low frame rate.

Solutions:

1. Lower the bitrate (try 1000-2000 kbps for standard LAN use).
2. Reduce the FPS setting.
3. Use wired Ethernet instead of WiFi.
4. Check for network congestion or high bandwidth usage from other applications.
5. Ensure UDP port 5004 is not blocked or rate-limited.

Remote desktop shows black screen

Symptoms: The remote desktop window opens but shows only black.

Solutions:

1. Verify the client is online and responsive (try taking a screenshot first).
2. Check UDP port 5004 is open bidirectionally.
3. The client's graphics driver may need updating.
4. Try requesting a keyframe refresh.

Cannot control mouse or keyboard remotely

Symptoms: You can see the remote screen but clicks and keystrokes have no effect.

Solutions:

1. Verify the remote management port (TCP 5003) is open.
2. Check that the client application has appropriate system permissions.
3. Some fullscreen games may block remote input.

Licensing Issues

License shows "offline_grace"

Symptoms: License status shows offline_grace with a countdown.

Solutions:

1. Restore internet connectivity on the server PC.
2. Check DNS resolution. The server must reach the licensing server.
3. Check for proxy or firewall blocking outbound HTTPS connections.
4. You have 72 hours to restore connectivity before the server locks.

License shows "over_limit"

Symptoms: More clients are connected than the license allows.

Solutions:

1. Disconnect idle clients that are not in use.
2. Check the current client count vs your license limit.
3. Upgrade your license for more PC capacity.
4. Note: consoles count toward the total PC limit.

License shows "expired" or "revoked"

Symptoms: Server enters restricted mode.

Solutions:

1. Check your license expiration date.
2. Renew your license through the HandyCafe website.
3. For revoked licenses, contact HandyCafe support.

General Issues

Settings changes are not being saved

Symptoms: Changes revert after navigating away from settings.

Solutions:

1. Make sure to click the Save button after making changes.
2. Check for validation errors (highlighted fields with error messages).
3. Verify you have admin permissions.

Audit logs are missing entries

Symptoms: Expected actions do not appear in the Logs page.

Solutions:

1. Check the log filters. Ensure the correct category and date range are selected.
2. Verify LOG_DISPLAY_FULL permission is granted (otherwise only today's logs are shown).
3. Search using the text search field for the specific action.