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
"We could not determine the room for this reservation."	The PMS room lookup returned no usable room	Retry room resolution
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
"Request timezone does not match the hotel timezone" or "Hotel timezone configuration is invalid"	The hotel timezone is missing, invalid, or conflicts with request metadata	Check Opera timezone settings
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
Be-Tech client or service stops after restart or manual stop	The agent is recovering the local vendor client	Wait for Be-Tech recovery
"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 asks you to select an encoder	Multiple GreatLocks servers or agents are available	Select the GreatLocks encoder
GreatLocks inventory does not load	Agent tunnel, server record, or inventory source issue	Check GreatLocks inventory sync
PMS encoder discovery returns no results	Wrong PMS vendor, or the PMS exposes no terminals	Check PMS discovery
Opera route is ambiguous or incomplete	Opera returned duplicate or missing Door Lock routing details	Fix Opera route details
"OPERAWS-FOF01920" appears during a card read	An old or invalid interface value was sent to Opera	Refresh the Opera route
"OPERAWS-FOF00199" appears during a card read	Opera cannot reach the configured Door Lock System	Check Door Lock connectivity
PMS card reading is unavailable	Reading setting, PMS capability, or active encoder issue	Check PMS card reading
No card is detected	The reader found no card	Reinsert the card
Card type is unsupported	A card is present, but the encoder does not recognize its type	Use a supported card
Card cannot be read	A card is present, but the encoder cannot read its data	Try another card
Opera card read shows a generic failure	Opera returned an empty or invalid card response	Check the Opera card response
PMS kiosk cannot resolve its encoder	Device Model and legacy kiosk mappings use different labels	Check PMS kiosk mapping
"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
Heartbeat shows unknown	AVA could not verify the encoder state	Check unknown status
Heartbeat reports a status or tunnel error	The diagnostic check or agent tunnel failed	Check the reported error
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
"This Windows Agent is too old to read keycards"	The installed agent does not include Read Keycard	Update the Windows Agent
"The encoder tunnel is offline"	The Universal Encoder Agent tunnel is unavailable	Reconnect the encoder tunnel
Windows asks for permission	Tray service control needs elevation	Approve the UAC prompt

Reservation room cannot be resolved

What you see: After selecting an encoder, AVA says "We could not determine the room for this reservation."

Why this happens: The authenticated PMS lookup returned no usable room identity.

Fix:

1. Refresh the reservation or Operations View.
2. Confirm the reservation has an assigned room in your PMS.
3. Start the reservation, check-in, or key management flow again.
4. Select an online encoder when AVA asks.
5. Contact support if the message returns after the PMS room is assigned.

AVA accepts valid PMS room identities, including long AVA PMS identifiers. Do not shorten or edit the PMS room identity manually.

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. Staff alerts and the related log details use the same normalized failure category. For example, a card-present error is not reported as No card detected.

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.
   • No card detected: Reinsert the card and check its placement.
   • Unsupported card type: Use a card type supported by this encoder.
   • Card could not be read: Try another card and check for damage.
   • 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.

Opera timezone mismatch

What you see: The keycard flow stops before PMS returns a room key. You may see "Request timezone does not match the hotel timezone" or "Hotel timezone configuration is invalid."

Why this happens: AVA formats Opera keycard validity as the property's local wall clock, not UTC. It fails closed when the hotel timezone is missing or invalid. It also fails when request timezone data conflicts.

Fix:

1. Go to Settings → Essentials → Hotel Basic Details.
2. Confirm Timezone is valid and matches the property's local clock.
3. Save the change if you update it.
4. Refresh the reservation or reopen the keycard flow.
5. Try the keycard request again.

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.

PMS encoder discovery returns no results

What you see: You click Load Encoders, but AVA shows no PMS terminals.

Why this happens: The PMS vendor setting does not match your property, or your PMS is not exposing encoder terminals.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Confirm the PMS vendor matches your property.
3. Click Save again.
4. Return to Physical Encoder Devices and click Load Encoders.
5. If the list is still empty, confirm your PMS integration is active.
6. If your PMS still exposes no terminals, contact support with your vendor name and property name.

PMS card reading is unavailable

What you see: Entitlements does not show Start scanning, or it says physical keycard reading is unavailable.

Why this happens: Reading is disabled, the PMS adapter does not support it, or capability lookup is temporarily unavailable. PMS card reading also requires an active PMS encoder.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Select PMS Integration.
3. Confirm Enable PMS Encoder Integration is on.
4. Confirm the PMS vendor matches your property.
5. Confirm a discovered encoder is Active.
6. Turn on Enable physical keycard reading, then click Save.
7. Reload Entitlements and check for Start scanning.
8. Use Look up by room or Look up by confirmation number while reading is unavailable.

PMS card reads use the PMS transport directly. They do not require a Universal Encoder Agent session. If the warning remains, your PMS adapter may not advertise reading support yet.

Opera route is ambiguous or incomplete

What you see: Opera card reading stays unavailable after you load an encoder.

Why this happens: Opera returned duplicate or incomplete workstation, encoder, interface, or outbound-code details. AVA fails closed instead of sending a card read to the wrong Door Lock route.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Confirm the PMS vendor is Opera.
3. Confirm the intended encoder is Active.
4. Click Load Encoders, then Add Selected when the correct terminal appears.
5. Ask your Opera administrator to correct duplicate or missing Door Lock interface details.
6. Reload Entitlements after the encoder catalog is corrected.
7. Use Look up by room or Look up by confirmation number meanwhile.

Contact support if the route remains unavailable after Opera confirms one exact route.

Opera interface validation error

What you see: A card read shows OPERAWS-FOF01920 or an interface-number validation error.

Why this happens: Opera rejected the request's interface value. This can happen when an older route remains cached after encoder details change.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Confirm the Opera encoder's workstation and encoder ID match the physical device.
3. Click Load Encoders, then Add Selected for the current terminal.
4. Confirm the encoder is Active.
5. Reload Entitlements, then try Start scanning again.
6. Use Look up by room or Look up by confirmation number if scanning still fails.

AVA uses values such as SL01 to select a Door Lock route. It uses the route's numeric outbound code for the physical read. Do not convert or edit the interface value yourself.

Contact support if OPERAWS-FOF01920 returns after you reload the current encoder.

Opera Door Lock System timeout

What you see: A card read shows OPERAWS-FOF00199 or a Door Lock System timeout.

Why this happens: Opera accepted the request but could not reach the configured Door Lock System. This is an operational connectivity issue, not a missing-card result.

Fix:

1. Confirm the Saflok interface and encoder are powered on.
2. Check the property network connection to the Door Lock System.
3. Confirm the Opera Door Lock interface is online.
4. Reinsert the card and try Start scanning once.
5. Use Look up by room or Look up by confirmation number while the interface is offline.
6. Ask your Opera administrator to check Door Lock System and encoder connectivity.

Do not treat this error as No card detected. Contact support if the interface remains online but reads continue to time out.

Card type is unsupported

What you see: AVA says the card type is unsupported or unrecognized.

Why this happens: A card is present, but this encoder does not recognize its type. This is different from a missing card.

Fix:

1. Remove the card from the encoder.
2. Confirm you are using the card type approved for this encoder.
3. Place a supported blank card on the encoder.
4. Try encoding the keycard again.
5. If the message returns, ask your manager to confirm the encoder and card setup.

Do not keep repositioning the card when AVA identifies an unsupported card type.

Card cannot be read

What you see: AVA says the card could not be read or the card read failed.

Why this happens: A card is present, but the encoder cannot read its data. The card may be damaged, incompatible, or incorrectly placed.

Fix:

1. Remove the card from the encoder.
2. Check the card for visible damage.
3. Reinsert the card with the correct side facing up.
4. Try a different supported card if the error returns.
5. Contact support if several known cards cannot be read.

No card is detected

What you see: AVA reports that no card was detected after you start a PMS card scan.

Why this happens: The reader found no card on the encoder. This is different from an unsupported card type or an unreadable card.

Fix:

1. Remove the card from the reader.
2. Reinsert the card with the correct side facing up.
3. Wait for the reader to finish, then try the scan again.
4. Use Look up by room or Look up by confirmation number if the card still does not read.
5. Contact support if several known cards return no card.

Opera card read shows a generic failure

What you see: AVA shows a generic PMS keycard read failure after Opera returns HTTP 200.

Why this happens: Opera may return departure date and time ranges instead of older validity fields. AVA accepts non-empty ranges and uses their end as the card checkout time. Empty or malformed ranges remain invalid.

Fix:

1. Confirm the card was encoded by Opera and belongs to the expected reservation.

2. Reinsert the card and select Start scanning again.

3. If AVA reads the card without a room, use Look up by room or Look up by confirmation number.

4. If the generic failure continues, use manual lookup and ask your Opera administrator to check the card data.

5. Contact support with the scan time, property, and encoder name.

   ✓ A valid Opera card should appear as read data, even when Opera does not include a room.

PMS kiosk encoder mapping is not resolved

What you see: A PMS kiosk cannot encode a card, although the encoder appears in Physical Encoder Devices.

Why this happens: The kiosk's Device Model mapping and legacy kiosk mapping can use different labels. AVA uses the Device Model mapping first, then falls back to the legacy mapping.

Fix:

1. Go to Settings → Kiosk → Device Routing.

2. Find the affected kiosk and check its target encoder mapping.

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

4. Confirm the matching PMS encoder is Active under Physical Encoder Devices.

5. If the target changed, save the mapping with the encoder's current PMS name.

6. Retry encoding one test card from the kiosk.

   ✓ AVA should resolve the kiosk to the active PMS encoder and send the request.

If the encoder is missing from Physical Encoder Devices, follow PMS encoder discovery returns no results.

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.

Be-Tech reachability checks

AVA treats a 405 response as reachable because some Be-Tech deployments do not support the check method. It treats 401, 404, and 5xx responses as 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 or service stops after restart or manual stop

What you see: The Be-Tech client or service is stopped after Windows restarts or manual stops. AVA may briefly show the encoder as unavailable.

Why this happens: The Be-Tech client can start separately from the Windows Agent. The tray now detects the installed client and recovers its service automatically.

Fix:

1. Leave the Windows Agent service running on the encoder computer.
2. Wait briefly for the tray to show a Be-Tech recovery notification.
3. Wait for the notification that says the Be-Tech client service is running again.
4. Refresh Settings → Room Access → Keycard Encoding.
5. Confirm the agent and encoder show Connected or Online.
6. Retry the keycard operation.

Automatic retry

If recovery fails, the tray retries automatically. Use the tray Restart action only if recovery continues failing.

If the hotel has multiple Be-Tech installations, ask your deployment admin about BETECH_CLIENT_PATH. The path must point to the trusted Program Files installation.

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 cannot reach the local Be-Tech client service. The tray may already be recovering the client or service.

Fix:

1. Go to the encoder computer.
2. Check for a Be-Tech recovery notification in the Windows tray.
3. Wait briefly, then refresh Settings → Room Access → Keycard Encoding.
4. If the agent remains offline, use the tray Restart action.
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 first active GreatLocks row 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 encoder selection required

What you see: A GreatLocks status or configuration action asks you to select an encoder.

Why this happens: Each Universal Encoder Agent serves one GreatLocks encoder. AVA cannot safely choose a target when multiple servers or agents are available.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Open Physical Encoder Devices.
3. Confirm each GreatLocks row has exactly one Encoder ID. Use a different ID for every physical encoder.
4. Select the encoder connected to the Windows PC you need.
5. Confirm its agent is Online.
6. Save, then repeat the status, configuration, or test action.

Separate encoder status

Each GreatLocks encoder keeps its own live status. One online agent does not make another encoder online.

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. If several GreatLocks encoders exist, select the encoder linked to this inventory.
4. Check that its agent tunnel shows a healthy connection.
5. Click Test Connection again.
6. 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.

Status meanings

Online means AVA verified the encoder and tunnel. Offline means AVA verified that the encoder is unavailable. Unknown means AVA could not verify the encoder state. Unknown does not automatically mean the encoder is offline.

Encoder status shows unknown

What you see: Heartbeat Monitor shows unknown, but the agent session and tunnel are healthy.

Why this happens: Optional vendor diagnostics may be unavailable. Missing optional Saflok Ambiance credentials can produce an unverified status.

Fix:

1. Check Registered Agents and confirm the agent is connected.
2. Confirm Last Seen is recent and the tunnel is reachable.
3. Do not restart or reinstall the agent based on unknown alone.
4. Test one keycard if you need to confirm the encoder still works.
5. Contact support if a status error continues or encoding fails.

Heartbeat status or tunnel error

What you see: Heartbeat reports a status error or a tunnel failure.

Fix:

1. Read the full message and note whether it names the encoder status or tunnel.
2. For a status error, check the vendor diagnostics and capture the exact message.
3. For a tunnel failure, confirm the agent is running and Last Seen is recent.
4. Refresh Settings → Room Access and check the status again.
5. Contact support if the error remains or keycard encoding fails.

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 after verifying the agent and tunnel. An Unknown result means the encoder state is unverified, not confirmed offline. That same status now drives dynamic encoder selection. For GreatLocks, the status belongs only to the encoder associated with that agent.

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 too old to read keycards

What you see: Read Keycard fails with "This Windows Agent is too old to read keycards. Update the Universal Encoder Agent, then try again."

Why this happens: Older Universal Encoder Agent builds do not expose the Saflok read API. AVA then hits the hotel PC's default web page instead of the agent.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. If the Windows Agent shows outdated, click Update before Reinstall.
3. Wait for the agent to reconnect.
4. Try Read Keycard again.

Encoder tunnel is offline

What you see: Read Keycard shows "The encoder tunnel is offline. Start the Universal Encoder Agent, then try again."

Why this happens: The encoder computer cannot reach AVA through its Universal Encoder Agent tunnel. This differs from an outdated agent, which needs an update.

Fix:

1. Go to Settings → Room Access → Keycard Encoding.
2. Find the Saflok Windows Agent card.
3. Start the Universal Encoder Agent on the encoder computer.
4. Wait until the agent shows Connected and its Last Seen time is recent.
5. Try Read Keycard again.
6. If the agent stays offline, follow Windows Agent not connected.

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