This guide addresses common technical issues, error messages, and workflow problems encountered when using the guest and visitor management system. Solutions are organized by user type and scenario to help you resolve issues quickly.
Most visitor problems stem from permission restrictions, date conflicts, or communication failures rather than technical bugs. Understanding the underlying policies helps diagnose issues faster.
If you encounter an issue not covered here, contact your housing technology support team with specific error messages and screenshots.
Resident Issues: Cannot Create Invitations
Error: "You are not allowed to invite visitors"
Cause: The resident's profile has guest invitation privileges disabled by housing administration.
Solution: The resident should contact their residence life office to inquire about their visitor privileges. Only administrators can enable this permission. Privileges may be restricted due to conduct probation, housing agreement terms, safety concerns, or administrative holds.
Verification: Administrators can check the resident's profile at /admin/students/[studentId] and look for the Can Invite Visitors toggle under permissions or guest settings. Enable this toggle to restore privileges if appropriate.
Error: "Visitors are not allowed during this time"
Cause: The selected arrival or departure dates fall outside the configured visitor schedule or within an exclusion date period.
Solution: Residents should choose different dates within the allowed visitor schedule. Open the invitation form and click the date picker to see which dates are available (shown in normal color) versus blocked (grayed out).
Verification: Administrators can review visitor schedules at /admin/visitors/config under the visitorSchedule JSON configuration and exclusionDates array. Verify whether the selected dates conflict with schedule restrictions or exclusions. Adjust policies if needed or inform the resident why those dates are unavailable.
Error: "Visit duration exceeds maximum allowed"
Cause: The time between arrival and departure exceeds the maxInvitationTimeInHours setting configured by the institution.
Solution: Residents should reduce the visit duration to fit within the maximum allowed hours. Common limits are 24, 48, or 72 hours. Alternatively, create multiple back-to-back invitations to cover a longer visit with check-out and re-check-in at the transition.
Verification: Administrators can check the duration limit at /admin/visitors/config in the maxInvitationTimeInHours field. Increase this value if longer visits should be permitted, or explain the policy to the resident if exceptions aren't allowed.
Error: "This person is banned and cannot be invited"
Cause: The visitor's email address or phone number matches a banned visitor record in the system.
Solution: Residents cannot invite banned individuals. They should contact their residence life office if they believe the ban is an error or involves a different person with similar contact information.
Verification: Administrators can search for the visitor at /admin/visitors and check their status. If the visitor appears with Banned status, review the ban reason and date. Unban the visitor if appropriate by opening their detail page and clicking Unban Visitor.
Error: "Please enter a valid email address"
Cause: The email address format is incorrect, contains spaces, or has typos.
Solution: Residents should carefully re-enter the email address, checking for common mistakes like missing "@" symbols, spaces, incorrect domain endings (e.g., ".con" instead of ".com"), or extra characters.
Resident Issues: Invitation Not Received
Visitor didn't receive invitation email
Cause: Email was filtered as spam, the email address was entered incorrectly, or email delivery failed.
Solution:
Visitor should check spam, junk, and promotions folders for emails from your institution's Housing.Cloud domain
Resident should verify the email address on the invitation is correct by viewing the invitation in their portal at /visitors
If the email is wrong, cancel the invitation and create a new one with the correct address
Resident can manually share the QR code link by copying it from the invitation details and sending via text message or social media
Verification: Administrators can check email delivery logs if your institution has access to email server logs. Verify whether the email was sent successfully or bounced. If emails consistently fail to deliver, review email template configuration at /admin/setup/forms/guest under the invitation email template.
Multiple invitations sent by mistake
Cause: Resident submitted the invitation form multiple times, creating duplicate invitations.
Solution: Resident should cancel the duplicate invitations by navigating to /visitors, opening each duplicate, and clicking Cancel. Keep only the correct invitation active. The visitor may receive multiple emails but should use the QR code from the non-canceled invitation.
Staff Issues: QR Code Won't Scan
Scanner doesn't read the QR code
Cause: Low screen brightness, dirty camera lens, wrong distance, or damaged QR code image.
Solution:
Ask the visitor to increase screen brightness to maximum
Clean the camera lens on the scanner device
Adjust distance between code and camera to 6-12 inches
Try scanning from a different angle if screen glare is present
If scanning fails repeatedly, switch to manual check-in by searching for the invitation at /staff/visitors
Verification: Test the scanner with a known-working QR code to verify the scanner hardware and software function properly. If the scanner fails on all codes, restart the scanner app or device. Contact IT if scanner hardware is malfunctioning.
QR code displays an error after scanning
Cause: The invitation was canceled, the visitor is banned, or the QR code is for a past or invalid invitation.
Solution:
If status shows Canceled, inform the visitor their invitation was canceled and ask them to contact their host
If status shows Banned, politely explain you cannot complete check-in and suggest they contact the residence life office
If the invitation is for a different date, verify with the visitor when they're supposed to arrive and whether they have the correct invitation
Verification: Search for the visitor at /staff/visitors to see all their invitations. Check dates, statuses, and history to determine why the scanned code isn't valid.
Staff Issues: Check-In Button Disabled
Cannot click Check In after scanning
Cause: Required check-in form fields are incomplete, the visitor is already checked in, or staff lacks the checkInGuests permission.
Solution:
Scroll through the check-in form to ensure all required fields are completed. Required fields are marked with asterisks or "required" labels
Check the invitation status—if it shows Checked-In, the visitor was already processed. Verify the check-in timestamp
Verify your staff account has the checkInGuests permission by checking your profile or asking a supervisor
Verification: Administrators can verify staff permissions at /admin/staff or the staff user management page. Ensure the staff member's role includes checkInGuests permission. If the invitation already shows Checked-In, review the check-in timestamp and staff member who performed it to determine if it was correct or accidental.
Check-in form won't submit
Cause: Browser error, network connectivity issue, or validation error on form fields.
Solution:
Check for error messages near form fields indicating which fields have validation problems
Verify network connection is active and stable
Refresh the page and re-scan the QR code to reload the form
Try using a different browser or device if the issue persists
Verification: Administrators can review check-in form configuration at /admin/setup/forms/guest under guestCheckInFormTemplate. Verify required fields are configured properly and validation rules are reasonable. Test the form yourself to reproduce the issue.
Staff Issues: Check-Out Problems
Visitor shows as already checked out
Cause: Automatic check-out ran at the scheduled departure time, or another staff member already checked them out.
Solution: Inform the visitor they're already checked out in the system. Review the check-out timestamp on the invitation detail page to see when it occurred. If it was automatic check-out, explain that the system handled it automatically. If manual, note which staff member completed it.
Verification: Administrators can check whether automatic check-out is enabled at /admin/visitors/config in the autoCheckOut setting. If enabled, check-out happens automatically at scheduled departure times without staff action.
Cannot check out a visitor who left early
Cause: The invitation status is incorrect, the visitor was never checked in, or technical error.
Solution:
Verify the visitor's status shows Checked-In. Only checked-in visitors can be checked out
If status shows Invited, the visitor was never checked in. You cannot check out someone who never checked in
Search for the correct invitation if multiple exist for the same visitor
Verification: Review the invitation history to see all status changes and timestamps. Verify check-in occurred before attempting check-out.
Admin Issues: Configuration Not Saving
Visitor schedule changes don't apply
Cause: JSON syntax error in the visitorSchedule field, network error during save, or permission issue.
Solution:
Verify the JSON syntax is correct with proper brackets, commas, and quotation marks. Use a JSON validator tool to check formatting
Ensure you have the manageGuestManagement permission to edit visitor configuration
Check browser console for JavaScript errors that might prevent saving
Refresh the config page after saving to verify changes persisted
Example valid visitorSchedule JSON:
{
"monday": {"start": "18:00", "end": "23:59"},
"friday": {"start": "17:00", "end": "23:59"},
"saturday": {"start": "00:00", "end": "23:59"},
"sunday": {"start": "00:00", "end": "20:00"}
}Exclusion dates not blocking invitations
Cause: Date format incorrect, timezone mismatch, or dates not saved properly.
Solution:
Verify exclusion dates use the correct format, typically YYYY-MM-DD
Ensure date ranges have both start and end dates
Save the configuration and test by attempting to create an invitation during an exclusion period
Clear browser cache and reload the config page to ensure you're seeing current settings
Email templates show variable syntax instead of values
Cause: Template variables are incorrectly formatted or the template rendering engine has an error.
Solution:
Check template variable syntax matches the expected format, typically
{{variableName}}Verify you're using documented variable names like
{{hostName}},{{visitorName}},{{arrivalDate}}Test the template by sending a test invitation and checking the email received
Revert to the default template if custom edits caused issues, then modify incrementally
Verification: Review the invitation email template at /admin/setup/forms/guest. Compare your template to the default template or documentation to identify incorrect variable syntax.
Admin Issues: Form Configuration Problems
Custom form questions don't appear for residents
Cause: Form is not published, form fields are configured incorrectly, or caching issue.
Solution:
Verify the invitation form template is Published at /admin/setup/forms/guest. Archived forms don't appear to users
Check that form fields have proper configuration including field types, labels, and required status
Test by creating an invitation yourself as a resident to verify the form displays correctly
Clear browser cache or test in an incognito/private window
Required form fields allow submission when blank
Cause: Field required setting is not enabled, or client-side validation is not working.
Solution:
Edit the form template at /admin/setup/forms/guest and ensure the Required toggle is enabled for fields that must be completed
Save and republish the form
Test submission with blank fields to verify validation works
Performance Issues: Slow Loading
Visitor list loads slowly with many records
Cause: Large dataset with hundreds or thousands of visitor records loading at once.
Solution:
Apply filters to narrow the dataset before loading, such as filtering to only checked-in visitors or today's date
Use search to find specific invitations rather than scrolling through complete lists
Export data to CSV for offline analysis if you need to review large datasets
Archive old visitor records if your system supports archiving to improve performance
QR scanner is slow to activate camera
Cause: Browser permission issues, hardware limitations, or software conflicts.
Solution:
Grant camera permissions when prompted by the browser
Close other apps or browser tabs using the camera
Restart the browser or device
Use a dedicated QR scanner app or device instead of browser-based scanning
Data Sync and Notification Issues
Resident not receiving guest arrival notifications
Cause: Notification preferences disabled, email/SMS delivery failure, or notification system error.
Solution:
Resident should check notification preferences in their profile settings and enable guest arrival notifications
Verify email and phone number in the resident's profile are correct and current
Check spam folders for notification emails
Test by having staff manually trigger a notification if available
Verification: Administrators can review notification event configuration to ensure GUEST_ARRIVED and GUEST_WAITING events are enabled and configured to send to residents.
Invitation status not updating in real time
Cause: Browser caching, network latency, or refresh needed.
Solution:
Refresh the page to load the latest data
Check network connection stability
Clear browser cache and reload
Verify the action (check-in, check-out, cancel) completed successfully by viewing the invitation detail page
Permission and Access Issues
Staff cannot access visitor management pages
Cause: Missing viewGuestManagement or checkInGuests permission, or feature not enabled for the institution.
Solution:
Administrators should verify the guest management feature is enabled by checking for the GUEST_MANAGEMENT feature flag
Add the viewGuestManagement permission to the staff member's role or individual profile to allow viewing visitor records
Add the checkInGuests permission to allow check-in and check-out operations
Contact Housing.Cloud support if the feature flag is not available
Administrator cannot access config page
Cause: Missing manageGuestManagement permission.
Solution: Ensure the administrator role includes the manageGuestManagement permission. This permission controls access to visitor configuration, forms, and policy settings at /admin/visitors/config. Only administrators with this permission can modify guest management settings.
When to Contact Support
Contact your Housing.Cloud support team if you encounter:
Error messages not listed in this guide
System-wide failures affecting multiple users
Data loss or corruption in visitor records
Security concerns about banned visitor bypass attempts
Feature requests for functionality not currently available
Integration issues if your institution uses custom SIS connections
When contacting support, provide specific details including error messages, screenshots, user roles involved, steps to reproduce the issue, and timestamps when the problem occurred.
Related Articles
Guest and Visitor Management Overview
Setting Up Guest Management Policies (Admin)
Creating Guest Invitations (For Students)
Checking In Guests with QR Codes (For Staff)