Troubleshooting Guest and Visitor Issues

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.

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)