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
Plain-language keycard failure	AVA normalized a vendor, room, or session error	Read the message
"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
"Please create a new keycard first, then use Duplicate for any extra cards."	Saflok cannot find an existing active registration for the reservation	Fix the missing first keycard
Multi-room Saflok/Ambiance card needs a room-level ID	The selected room does not have its own sub-reservation yet	Check the selected room
"The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."	The encoder has no active session	Check the encoder session
Raw DoorLock generate fail or internal error text appears	A technical room-access payload leaked through the modal	Use the generic retry path
Encoder type change does not stick	Previous save left mixed encoder states	Re-save encoder type
"Test Connection" fails (Be-Tech) or agent stays offline	Base URL, adapter, or service issue	Fix Be-Tech connection
"Make sure the Be-Tech client program is running on the encoder computer."	The Windows Agent returned a 502 vendor-unavailable response	Check the Be-Tech client program
"Test Connection" fails (GreatLocks)	Saved GreatLocks server details are missing or stale	Fix GreatLocks connection
GreatLocks inventory does not load	Agent tunnel, server record, or inventory source issue	Check GreatLocks inventory sync
"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	Dynamic lists still see the agent as disconnected	Check live encoder status
Windows Agent shows Not connected	Agent not running or install incomplete	Reconnect agent
Windows asks for permission	Tray service control needs elevation	Approve the UAC prompt

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.

Normalized encode failures

What you see: The reservation modal shows a short, plain-language message instead of a raw vendor string.

Why this happens: AVA now preserves normalized Saflok, Be-Tech, Opera, and internal session failures before showing them. It prefers the structured message first, then falls back to older vendor-string parsing when needed. HTTP 504 room-access timeouts stay on this same path with KEYCARD_VENDOR_TIMEOUT.

Fix:

1. Read the short message first.
2. Look for userMessage, errorCode, retriable, vendor name, and safe upstream details in support views.
3. Use those details when you contact support.
4. Match the message to the most likely fix below:
   • Occupied room: Refresh the reservation, then try again.
   • Encoder offline: Check power, network, or agent status.
   • Failed detect/write: Reinsert the card or use a new blank card.
   • No active session: Reconnect the encoder session.
   • Missing mapping: Confirm the room mapping is correct.
   • Invalid room or date: Verify the stay dates and room assignment.
   • Vendor auth, gateway, or timeout: Check vendor access or retry later.
   • HTTP 504 timeout: Retry after a short wait.
   • Invalid request: Reopen the correct reservation and try again.
5. If retriable is true, retry after a refresh.
6. If retriable is false, fix the mapping or vendor issue first.

Legacy fallback stays on

Older responses can still show legacy vendor strings. AVA keeps that parsing path so historical logs and older integrations still read correctly.

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.

Automatic Saflok recovery

If Saflok PMSI starts slowly or restarts later, AVA rechecks readiness every 10 seconds. Wait briefly, then refresh before reinstalling the agent.

1. Check the Windows Agent is connected in AVA

1. Go to Settings → Room Access → Keycard Encoding.

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. If Saflok PMSI was still starting, wait 10 seconds and refresh once before reinstalling anything.

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 duplicate keycard needs a first keycard

What you see: AVA shows "Please create a new keycard first, then use Duplicate for any extra cards."

Why this happens: Saflok could not find an active registration or keycard record for that reservation. Duplicate cards need one successful first keycard before AVA can add more.

Fix:

1. Create the first keycard for the reservation.
2. Wait for the first encoding to complete successfully.
3. Select Duplicate only after the first keycard exists.
4. If the error returns, confirm the reservation still has an active registration in Ambiance.
5. Try the duplicate request again.

What you should not see

You should not see raw ReservationNotFound or SOAP fault details in the message.

Saflok/Ambiance multi-room keycards need a room-level reservation ID

What you see: You try to encode a card for one room in a multi-room stay, and AVA stops the flow.

Why this happens: Saflok/Ambiance duplicate cards use the selected room's sub-reservation ID. If that room does not have its own ID yet, you see a fail-fast error.

Fix:

1. Open the reservation and choose the exact room row you want.
2. Wait for PMS sync if the room was just split or moved.
3. Confirm the room exists as its own sub-reservation in your PMS.
4. Try Encode Keycard again.

Encoder has no active session

What you see: AVA shows "The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."

Why this happens: The encoder does not have an active session right now. AVA treats this as an offline readiness issue.

Fix:

1. Confirm the encoder is powered on and connected.
2. Refresh Settings → Room Access → Keycard Encoding.
3. Check whether the encoder shows Online or Connected.
4. Try encoding again after the session reconnects.
5. If it still fails, use a different encoder or contact support.

Raw room-access payload shows in the modal

What you see: The modal shows raw text such as DoorLock generate fail! or internal error.

Why this happens: AVA caught a technical room-access blob. It now falls back to the generic retry message instead of showing the raw payload.

Fix:

1. Close the modal.
2. Wait a few seconds.
3. Try encoding the keycard again.
4. If the same message returns, confirm the encoder is online.
5. If it still fails, switch to another encoder or contact support.

Saflok credentials not provided

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

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
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 → Keycard Encoding.
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.

Use this when you intentionally configured a direct Base URL or see a generic Be-Tech request failure. If you see the client program message, use Be-Tech client program unavailable.

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. If you use the Windows Agent, confirm the agent card is Connected.
5. Re-enter Hotel Name, Chain No, Workstation, and Reader No.
6. Click Test Connection again.

Be-Tech client program unavailable

What you see: AVA shows "Make sure the Be-Tech client program is running on the encoder computer."

Why this happens: The Windows Agent returned Be-Tech's vendor-unavailable 502 response. AVA now shows a direct message for that case.

Fix:

1. Go to the encoder computer.
2. Confirm the Be-Tech client program is running.
3. Restart the client program if it is stopped.
4. Restart the Windows Agent if the client program is already running.
5. Click Test Connection again.

Other Be-Tech failures

If you see Be-Tech request failed, follow Be-Tech test connection fails. The direct client-program message only applies to the 502 vendor-unavailable response.

GreatLocks test connection fails

What you see: Test Connection fails after you edit GreatLocks server details.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Confirm the GreatLocks server has an XHLSI Server IP Address and TCP Port.
3. Click Save again.
4. If you updated an older setup, keep the existing server record.
5. Click Test Connection again.

GreatLocks inventory does not load

What you see: Building, floor, or room inventory stays empty for GreatLocks.

Why this happens: The GreatLocks tunnel is offline, or the inventory source is not reachable.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Confirm the GreatLocks server record is saved.
3. Check that the agent tunnel shows a healthy connection.
4. Click Test Connection again.
5. Refresh the page after the connection returns.

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 → Keycard Encoding.
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. Rotate Secret opens a confirmation dialog before AVA disconnects the current agent.

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 → Keycard Encoding.
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 in the reservation modal.

Why this happens: AVA shows online only when the agent is connected and the tunnel is reachable. That same status now drives dynamic encoder selection.

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 download-installer.bat.
2. Let it download the installer .exe, then run that file.
3. Confirm the Windows PC has internet access.
4. Click Reinstall on the agent card in Windows Agent if needed.
5. If this is a Be-Tech setup, also confirm the local adapter service is running. Be-Tech status can take up to 5 minutes to refresh after a restart.
6. Refresh Registered Agents status.
7. Return to Settings → Room Access and confirm Status: changes to online.

Dynamic encoder lists

When the agent is connected and the tunnel is reachable, dynamic encoder lists should show Online. If a nested encoder card still looks offline, refresh the page and check the agent first.

Windows Agent service action needs permission

What you see: Windows asks for administrator permission when you click Start, Stop, or Restart.

Why this happens: The tray button needs elevated access to control the Windows service.

Fix:

1. Click Yes on the UAC prompt.
2. If you are not an admin, ask someone with admin rights to approve it.
3. Try the action again if you canceled the prompt.

Kiosk routing rules not showing

What you see: You can’t find routing rules under Room Access or the old Kiosk to Encoder Routing section.

Fix:

1. Go to Settings → Kiosk.
2. Open Device Routing.
3. Turn off Enable guest selection to show manual routing rules.
4. 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
• ❌ The Be-Tech client program keeps stopping
• ❌ Card encoding fails on multiple kiosks
• ❌ Heartbeat remains unhealthy for more than 30 minutes

Helpful to include:

• Encoder type and model
• The exact Be-Tech error message
• Whether you use Windows Agent or a direct Base URL
• Screenshot of Registered Agents and Heartbeat Monitor
• Time the issue started

Related Guides

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