Keycard Encoder Troubleshooting

Quick Fix

Check network and power first, then re-try encoding a single card. This takes about 2 minutes.

This guide helps you resolve common keycard encoder issues.

Quick reference

What you see	Why it happens	Do this
Encoder not responding	Power or network issue	Check connectivity
Cards not encoding	Card type or device issue	Verify card and device
"UserCredentialsNotProvided.NotApplicable"	Saflok credentials are missing or incomplete	Add Saflok credentials
Saflok/Ambiance encoding fails or times out	Windows Agent, Ambiance encoder service, or device is offline	Restart Saflok/Ambiance encoder
Encoder type change does not stick	Previous save left mixed encoder states	Re-save encoder type
"Test Connection" fails (Be-Tech)	Base URL or service issue	Fix Be-Tech connection
"Service URL is required" (LockSDK)	Direct mode needs a Service URL per encoder	Add LockSDK service URL
LockSDK agent shows Not registered	No per-encoder agent device exists yet	Register LockSDK agent
Heartbeat Monitor turns off after save	Save did not persist in your current hotel session	Re-save Heartbeat Monitor
Heartbeat shows unreachable	Agent offline or tunnel issue	Check agent status
Encoder stays unavailable	Connected state is false, even with a healthy heartbeat	Check live encoder status
Windows Agent shows Not connected	Agent not running or install incomplete	Reconnect agent

Encoder not responding

What you see: Encoder shows offline or no response in AVA.

Fix:

1. Check power and cabling for the encoder.
2. Verify network connectivity between kiosk and encoder (Direct Connection only).
3. Confirm the server IP and port are correct.
4. Restart the encoder software.

Cards not encoding

What you see: Keycard write fails or produces a blank card.

Fix:

1. Confirm the card type matches your encoder.
2. Reinsert the card and try again.
3. Test with a new blank card.
4. If Enable guest selection is off, verify the kiosk is routed to the correct encoder.
5. If Enable guest selection is on, confirm the guest selects an online encoder at the kiosk.

Saflok/Ambiance encoding not working

What you see: Keycard encoding fails, times out, or the kiosk reports no response from the Saflok/Ambiance encoder.

Fix: Work through these three checks in order. Each one rules out a common cause before you move to the next.

1. Check the Windows Agent is connected in AVA

1. Go to Settings → Room Access → Key Card Encoding (Kiosk).

2. Find the Windows Agent card for this encoder.

3. Confirm the status shows Connected and the Last Seen time is recent.

   

4. If the agent is Not connected, follow Windows Agent not connected before continuing.

2. Check the encoder is online in Ambiance

If the agent is connected but encoding still fails, log in to the Ambiance server and verify the encoder device.

1. Open Ambiance and go to Device Management → Encoders.

2. Find the encoder for this kiosk (for example, the Vouch encoder).

3. Confirm the Status shows Online.

   

4. If the encoder shows Offline, continue to step 3 to restart the encoder service.

3. Restart the Ambiance Encoder Service

If the encoder is offline in Ambiance, restart the encoder service on the computer where the Ambiance server is installed.

1. On the computer running the Ambiance server, press the Windows key or click the Start menu.

2. Type services manager and open Ambiance Services Manager from the results.

3. In the services list, select Ambiance Encoder Service.

   

4. Click the Stop (red square) button.

5. Wait a few seconds for the service state to change to Stopped.

6. Click the Start (red play) button.

7. Confirm the State returns to Running.

8. Go back to Ambiance Device Management → Encoders and confirm the encoder is Online.

9. Try encoding a test card from the kiosk.

Why a restart works

The encoder service can lose its connection to the physical encoder after network blips or long idle periods. Stopping and starting the service forces it to re-establish the link.

Saflok credentials not provided

What you see: "UserCredentialsNotProvided.NotApplicable" appears during keycard encoding.

Fix:

1. Go to Settings → Room Access → Key Card Encoding (Kiosk).
2. Set Encoder Type to Saflok.
3. Enter Username and Password in Encoder Credentials.
4. If direct communication is on, enter PMSI Server URL.
5. Click Save.
6. Click Test Connection, then encode one test card.

Encoder type change does not stick

What you see: You select one encoder type, but another encoder remains active.

Fix:

1. Go to Settings → Room Access → Key Card Encoding (Kiosk).
2. In Keycard Encoder Settings, select the encoder type you want.
3. Click Save once and wait for the success message.
4. Refresh the page and confirm only that encoder type is active.
5. If the issue repeats, switch types, save, then switch back and save again.

Be-Tech test connection fails

What you see: "Test Connection" shows a failure or the button stays disabled.

Fix:

1. Confirm the Base URL starts with http:// or https://.
2. Verify the Be-Tech service is running on the encoder workstation.
3. Check the workstation and kiosk are on the same network.
4. Re-enter Hotel Name, Chain No, Workstation, and Reader No.
5. Click Test Connection again.

LockSDK service URL is required

What you see: Save is blocked or encoder form shows "Service URL is required."

Fix:

1. Go to Settings → Room Access → Key Card Encoding (Kiosk).
2. Select LockSDK.
3. Open Physical Encoder Devices and edit the encoder.
4. Enter a valid Service URL like http://127.0.0.1:8092.
5. Click Save, then run Test Connection.

LockSDK agent not registered

What you see: A LockSDK encoder card shows Not registered in Windows Agent.

Fix:

1. Confirm the LockSDK encoder exists in Physical Encoder Devices.
2. Go to Windows Agent and find the encoder card.
3. Click Download Windows Agent if the card is new, or Reinstall if it already exists.
4. Extract the package and run the .bat file on the connected Windows PC.
5. Refresh status and confirm the card changes from Not registered to Connected or Not connected.
6. Use Advanced options only for View Logs, Rotate Secret, or Delete.

Heartbeat Monitor turns off after save

What you see: You enable Heartbeat Monitor, click Save, and it turns off again.

Fix:

1. Go to Settings → Room Access → Key Card Encoding (Kiosk).
2. Open Encoding Options → Advanced options.
3. Turn on Heartbeat Monitor.
4. Click Save once and wait for the success message.
5. Refresh the page and confirm Heartbeat Monitor is still on.
6. If it still turns off, follow Settings Not Saving After Switching Hotels.

Heartbeat failures

What you see: Heartbeat Monitor shows unreachable.

Fix:

1. Confirm the agent is running on the kiosk/PC.
2. Check Registered Agents for online status and tunnel reachability.
3. Review agent logs for errors.
4. Reinstall the agent if needed.

Live encoder status does not match

What you see: The encoder looks configured, but AVA still marks it unavailable.

Why this happens: AVA shows online only when the agent is connected and the tunnel is reachable.

Fix:

1. Check Registered Agents for the encoder card.
2. Confirm the device is connected and the tunnel is reachable.
3. Fix any agent or network issue first.
4. Refresh Settings → Room Access.
5. Try encoding again.
6. Recheck the Status: line on the settings page.

Windows Agent not connected

What you see: Status shows Not connected or "Never online."

Fix:

1. Open the downloaded zip and run the .bat file.
2. Confirm the Windows PC has internet access.
3. Click Reinstall on the agent card in Windows Agent if needed.
4. Refresh Registered Agents status.
5. Return to Settings → Room Access and confirm Status: changes to online.

Kiosk routing rules not showing

What you see: You can’t find routing rules under Kiosk to Encoder Routing.

Fix:

1. Check if Enable guest selection is on.
2. Turn it off to show manual routing rules.
3. Add at least one device in Physical Encoder Devices.

Still Stuck?

Contact success@vouch-technologies.com if:

• ❌ Encoders remain offline after power and network checks
• ❌ Card encoding fails on multiple kiosks
• ❌ Heartbeat remains unhealthy for more than 30 minutes

Helpful to include:

• Encoder type and model
• Screenshot of Registered Agents and Heartbeat Monitor
• Time the issue started

Related Guides

• Keycard Encoders Overview
• Set Up Keycard Encoders
• Keycard Guest Instructions