Skip to content

Troubleshooting

Solutions to the most common DFACS issues.

Door Doesn't Unlock on Valid Scan

Symptoms: Member scans, access log shows GRANTED, but door doesn't physically open.

Check these in order:

  1. Relay wiring — confirm lock is wired to NO (Normally Open) terminal, not NC
  2. Relay type — in Configuration, verify the relay type matches your hardware
  3. COM port — confirm the relay COM port is correct (check Device Manager)
  4. Test relay manually — Dashboard → Status → Test Unlock — if the relay clicks but the door doesn't open, the issue is electrical (lock wiring or power supply)
  5. Lock power supply — confirm the lock has adequate voltage and current (most door strikes need 12V at 500mA minimum)
  6. Unlock duration — if it's set to 1 second, the door may be unlocking too briefly to notice — increase to 5 seconds for testing

Door Doesn't Unlock — Access Denied

Symptoms: Member scans, access log shows DENIED.

Check the denial reason in the access log:

Reason Fix
EXPIRED_MEMBERSHIP Member's membership is expired in your gym software
UNKNOWN_BARCODE Barcode not in the member database — check if member exists in your platform
SUSPENDED Member account is suspended
NSF Member has a failed payment (Antaris/ABC)
OUTSIDE_SCHEDULE Scan happened during a restricted schedule window
API_UNAVAILABLE DFACS was offline and the barcode wasn't in the local cache

If the member should have access but is being denied, the most common cause is that the last sync hasn't picked up a recent membership change. Force a sync: Dashboard → Status → Force Sync.

Barcode Scanner Not Working

USB HID scanner:

  1. Unplug and replug the scanner
  2. Test it outside DFACS — open Notepad and scan a barcode; characters should appear
  3. Try a different USB port
  4. Check Device Manager for error indicators on the USB device

Serial scanner:

  1. Verify COM port in Configuration matches Device Manager
  2. Confirm baud rate matches the scanner's setting (check scanner manual)
  3. Unplug and replug the USB-to-serial adapter

Scanner reads but DFACS ignores it:

  • Check that the barcode format is one DFACS expects (Code 128, Code 39, etc.)
  • If using Hitone Fitness scanner: debouncing may be suppressing rapid scans — wait 2 seconds between scans during testing

API Connection Errors

Dashboard shows "API Disconnected" or "Sync Failed":

  1. Verify API credentials in Configuration are correct (copy/paste, no extra spaces)
  2. Check internet connectivity on the DFACS device (open a browser, go to google.com)
  3. Check if your gym platform is experiencing an outage (visit their status page)
  4. Review Dashboard → Error Log for specific error messages

Glofox: Confirm your Branch ID matches the branch in your Glofox account exactly.

Zenoti: Confirm the Center ID is correct — mismatches cause silent auth failures.

Fliip: French error messages in logs are normal — DFACS translates them automatically.

DFACS App Won't Start

System tray icon doesn't appear after Windows startup:

  1. Check Task Manager for a DFACS process — if present, right-click tray icon area and look for hidden icons
  2. If no process: navigate to the DFACS install folder and run DFACS.exe manually
  3. Check the log file for startup errors: C:\Program Files\DFACS\logs\dragonfly.log

DFACS crashes immediately on start:

  • Check Windows Event Viewer → Application for crash details
  • Verify the DFACS install isn't blocked by antivirus (add an exclusion for the DFACS folder)
  • Contact support with the content of dragonfly.log

Dashboard Not Accessible

Can't reach https://<ip-address> from another device:

  1. Confirm both devices are on the same network
  2. Verify the DFACS device's IP address (run ipconfig in Command Prompt on the DFACS device)
  3. Check Windows Firewall — DFACS needs port 443 open for inbound connections
  4. Try http:// instead of https:// as a test

Browser shows SSL warning:

This is normal for a self-signed certificate. Click Advanced → Proceed to site.

Offline / Not Syncing

Dashboard shows "Offline Mode":

  • DFACS is operating from its local cache
  • Members who were active at the last sync will still be able to scan in
  • Check internet connection and API credentials
  • When connectivity is restored, DFACS will automatically sync and process queued check-ins

Check-in queue is growing:

  • This is expected during an outage — check-ins are queued and will be sent when the API is reachable again
  • If the queue doesn't clear after the connection is restored, check Dashboard → Error Log

Fail-Safe Triggered (Door Unlocked Automatically)

DFACS will automatically unlock the door if system memory usage exceeds 85%. This is a safety feature — a locked door during a system failure could trap members.

If this happens:

  1. The dashboard shows a Fail-Safe Active warning
  2. The door will re-lock automatically when memory pressure clears
  3. Check what's using memory on the DFACS device (Task Manager)
  4. Restart the DFACS device if memory doesn't clear
  5. Contact support if this happens repeatedly

Still Stuck?

Collect this information before contacting support:

  • DFACS version (Dashboard → Configuration → bottom of page)
  • Your billing platform (Glofox, Zenoti, etc.)
  • Contents of dragonfly.log (last 100 lines)
  • Screenshot of the error log from the dashboard
  • Description of what you expected vs. what happened

Contact Support →