Troubleshooting

Solutions to the most common issues in Hygate.

Quick Diagnostics

Before diving into specific issues, check these first:

Check	How
Module health	Go to Dashboard — are all integrations green?
Stripe status	Check status.stripe.com
TTLock status	Check ttlock.com
Shelly status	Check shelly.cloud
Audit logs	Any recent errors logged?

Authentication Issues

Can't Log In

Cause	Solution
Wrong password	Click "Forgot Password" on the login page
Account deactivated	Contact an administrator to reactivate your account
2FA code wrong	Check that your authenticator app time is synced; try a fresh code
Email OTP not received	Check spam folder; verify the email address is correct
Session expired	Log in again with credentials and 2FA

2FA Setup Problems

Issue	Solution
Can't scan QR code	Manually enter the secret key displayed below the QR code
Lost authenticator app	Use a backup code or contact an admin to reset 2FA
Time mismatch	Enable automatic time sync in your authenticator app
Codes not working	Try the next code in sequence — old codes are invalid

Password Reset Not Working

Check that the reset email hasn't expired (links expire after 1 hour)
Try requesting a new reset link
Check spam folder
Verify you're clicking the link from the same browser where you requested it

Integration Issues

TTLock Connection Failed

Check	Action
Credentials	Verify Client ID, Client Secret, username, and password in Settings → TTLock
TTLock API status	Go to ttlock.com and check for service disruptions
Network	Ensure Hygate can reach euapi.ttlock.com
Account ownership	Verify your TTLock account owns the locks you want to sync

Still failing? Try re-entering credentials carefully (no extra spaces), then test again.

Shelly Connection Failed

Check	Action
Auth Key	Verify the Auth Key in Settings → Shelly matches what's in Shelly Cloud
Devices online	Check Shelly Cloud app — are your devices showing as online?
Network	Ensure Shelly devices are connected to WiFi
Server URL	Leave the server URL at its default unless you have a custom deployment

Stripe Webhook Not Working

Check	Action
Webhook URL	Verify the endpoint is configured as `https://your-domain/api/stripe/webhook`
Mode match	Ensure Stripe Dashboard is in the same mode (test/live) as your Hygate settings
Events subscribed	Check that `payment_intent.succeeded` and `charge.refunded` are both selected
HTTPS	Webhooks require HTTPS — ensure Hygate is served over TLS

Test locally: Use the Stripe CLI:

stripe listen --forward-to localhost:3000/api/stripe/webhook

Stripe Test Payments Not Working

Check	Action
Test mode	Ensure Hygate is using test API keys (`pk_test_`, `sk_test_`)
Test card	Use `4242 4242 4242 4242` with any future expiry and any 3-digit CVC
Card declined	Try `4000 0000 0000 0002` for a declined card to verify error handling
3D Secure	Use `4000 0025 0000 3155` to test 3D Secure flows

Payment Issues

Payment Failed — Card Declined

What guest sees: "Your card was declined. Please try a different card."

What to check:

The card may have insufficient funds
The card issuer blocked the transaction — guest should contact their bank
Try a different card

Payment Failed — Requires 3D Secure

What guest sees: Redirected to their bank's verification page

This is normal. 3D Secure adds an extra verification step. The payment completes after the guest completes the verification on their bank's page.

Payment Shows PENDING

Cause	Solution
Webhook not received	Check Stripe Dashboard → Developers → Logs for webhook delivery
Network timeout	Wait 30 seconds — Stripe may still deliver the webhook
Test mode keys used with live Stripe	Switch to correct keys

Payment Succeeded but No Access Code (Doors)

Check the Payments module — is there a SUCCEEDED payment record?
Check Audit Logs for payment_confirmed event
Check TTLock integration — did QR code generation succeed?
Verify the door is not in Maintenance Mode

Payment Succeeded but Session Didn't Start (Devices)

Check the Sessions module — is there an ACTIVE session?
Check Audit Logs for session_activated or shelly_on_failed
If shelly_on_failed appears — check Shelly device connectivity
Try manually turning the relay ON from the device page

Refund Not Showing

Verify the refund was initiated in Stripe Dashboard
Check for charge.refunded in Stripe webhook logs
Verify the REFUNDED status in Hygate Payments module
Refunds typically appear within seconds — wait 1-2 minutes before troubleshooting further

Door Issues

Door Not Syncing from TTLock

Verify TTLock integration is configured and green in Dashboard
Check that your TTLock account has the lock registered
Check TTLock developer portal for API rate limits
Try syncing again — some locks require multiple sync attempts

QR Code Won't Scan

Cause	Fix
Print quality too low	Re-print at 300+ DPI
Print too small	Ensure minimum 2.5cm × 2.5cm
Damage or smudges	Regenerate and reprint the QR code
Reflective surface	Place on matte surface; laminate with matte film
Wrong page loaded	Verify the QR code URL is correct

Door Stuck in Maintenance Mode

Go to Doors
Open the door detail page
Change status to Active
Save

If the status dropdown doesn't change or doesn't save, check your operator permissions — operators may not be able to change status.

Passage Mode Not Working

Passage mode must be configured in the TTLock app or TTLock Gateway settings, not in Hygate. Hygate only displays the current passage mode status.

To configure passage mode in TTLock:

Open the TTLock app
Select the lock
Find Passage Mode / Auto Unlock settings
Set your desired schedule
Verify in Hygate that the door status reflects the passage mode

Device Issues

Device Showing Offline

Check	Action
Shelly device power	Is the device powered on?
WiFi connection	Can the device reach your WiFi network?
Shelly Cloud status	Check shelly.cloud for service status
Shelly app	Can you control the device from the Shelly app directly?

If the device works in the Shelly app but shows offline in Hygate, try:

Re-syncing from Settings → Shelly
Re-entering the Auth Key
Checking for Shelly Cloud account issues

Relay Won't Turn On

Check the device is not in Maintenance Mode
Check there is no conflicting ACTIVE session on the same device
Check Audit Logs for shelly_on_failed — what's the error message?
Try the Power ON button again — relay commands have automatic retries
Manually test the device from the Shelly Cloud app

Session Stuck on "Finishing..."

This means the relay OFF command has been sent but the session hasn't marked as COMPLETED yet.

Wait up to 5 minutes — the cleanup cron runs every 5 minutes
If it persists after 5 minutes, go to Sessions
Find the session and click Force End

Session Cancelled Unexpectedly

Check audit logs for reconciliation events
Check for shelly_off_success or shelly_off_failed
Check Shelly device connectivity — did the device go offline?
Check power supply to the Shelly device

Wrong Usage Plan Charging

The price is locked at the time of payment creation. If the plan was changed after the payment was initiated but before it was confirmed, the old price applies.

If you need to correct the price:

Refund the payment in Stripe Dashboard
Adjust the usage plan in Hygate
Ask the guest to re-purchase

QR Code / Access Issues

QR Code PDF Generation Fails

Verify TTLock integration is configured
Check that the door has a valid uid (TTLock lock ID)
Try regenerating the QR code
Check browser console for JavaScript errors

Access Code Not Working at Lock

Verify the access code hasn't expired (check the access duration from the payment)
Ensure the guest is scanning the correct QR code from the access page
Try regenerating the QR access code from the door page
Check TTLock lock status — some locks require a specific orientation or position to scan

Dashboard and Reporting

Module Health Red

Module	Check
TTLock	Settings → TTLock credentials; ttlock.com service status
Shelly	Settings → Shelly Auth Key; shelly.cloud service status
Stripe	Settings → Stripe keys; Stripe Dashboard status

Reports Not Showing Data

Cause	Solution
No payments yet	Reports only show data after the first successful payment
Wrong date range	Try expanding the date range
Wrong location filter	Remove location filter to see all data
Timezone difference	Reports use the server's timezone

General Issues

Page Won't Load

Check	Action
HTTPS	Ensure you're accessing via HTTPS (required for webhooks and security)
Server running	Check that the Hygate server process is running
Browser cache	Clear browser cache or try incognito mode
Network	Check your network connection

Slow Performance

Check database connection pool — too many connections?
Monitor server CPU and memory
Check for long-running database queries in audit logs
Review cron job execution times

Data Missing or Incorrect

Check Audit Logs — was the action performed?
Check Reports — is the date range correct?
Check Filters — are filters hiding the data?
Try refreshing the page

Getting More Help

If you can't resolve an issue:

Check audit logs — they contain detailed event information
Check integration service status — Stripe, TTLock, Shelly
Gather diagnostic info — timestamps, user emails, payment IDs, error messages
Contact your administrator — they can check integration settings and credentials