Overview

Common problems with Access Packs v4 and how to diagnose them. Most issues fall into one of: missing encryption key, smart-lock connectivity, audience mismatch, or window mismatch.

How it works

"Saving the code returns a 500 error"

The API or worker is missing ACCESS_PACK_MASTER_KEY. This is a 32-byte base64 secret that encrypts every code value. Without it the encryption helper throws on first write.

Fix: Ask your operator or check the Railway environment for both staging and production. The key must be set on both the API and worker services. Vercel does not need it.

"Rotation stuck on 'in flight' for an Igloohome lock"

The Igloohome API never confirmed the PIN change. Usually one of:

  • Lock is offline (Wi-Fi or hub disconnected)
  • Lock battery is low
  • Igloohome partner subscription has lapsed

Fix: Open the Igloohome app and verify the lock is reachable. Reissue the rotation. If it keeps failing, rotate manually from the Reservation Access page as a fallback.

"Guest can't see the code"

Three common causes:

  1. Audience mismatch — the slot has audience cleaner and the guest pack filters it out. Open Property Access Settings and change the audience to guest or all.
  2. Window mismatch — the guest is opening the portal before the window opens. Check the Reservation Access page's window banner; extend if early arrival was granted.
  3. Pack revoked — somebody clicked Revoke. The guest sees an "Access revoked" notice. Re-rotate to restore.

"Codes didn't rotate after turnover"

The turnover checklist either lacks a rotate step, has one that's optional and was skipped, or has a manual rotation that wasn't filled in. Open the run, find the rotate step, check its status.

"Cleaner sees the wrong codes"

The cleaner's pack is filtered by audience. If your cleaner is seeing guest codes, the slot is tagged all instead of guest — and that's working as designed (all means everyone). If you want guest-only codes hidden from cleaners, change the slot audience to guest.

"Codes disappeared after 30 days"

That's the 30-day redaction worker — codes are permanently destroyed 30 days after check-out. Audit history remains. This is by design for compliance; you can't recover the values.

"My old guest still has the code"

Codes don't expire automatically when a guest checks out — they expire when the window closes or when you rotate. If you want belt-and-suspenders, wire a revoke_access_codes step into your check-out checklist.

Limits and requirements

  • The encryption key is NOT escrowed — losing both the Railway env value and any local backup is unrecoverable. Encrypted codes can never be decrypted again. This is acceptable in v4 because codes are rotatable; do not store long-durability secrets in an Access Pack slot until the escrow path lands.
  • Audit logs survive code redaction. Use them for dispute resolution.
  • Smart-lock connectivity is outside our control. Treat manual rotation as the fallback.

FAQ

Why doesn't the app warn me when ACCESS_PACK_MASTER_KEY is missing on boot?

It does — Railway logs the env-var check on each boot. But the app can boot without the key; the 500 happens on first write. We're considering a startup-time check.

What's the safest way to roll the master key?

Don't, unless you have to. v4 ships a encryption_key_id column on every encrypted value — when ready, we'll add a key-rotation worker that re-encrypts under a new id. There is no host-level UI for this yet.

Can I export every code for an off-platform backup?

No — the encryption is end-to-end inside our stack. There is no export endpoint. The 30-day window is your "go look at it before it's gone" affordance.

Can I recover a revoked pack?

Re-rotate the slots. Revoke + rotate together is a fresh pack. The old codes stay in audit but aren't surfaced.