Troubleshooting

6 min read Updated Oct 22, 2026

Introduction

This guide helps you resolve common issues with GuacamoleID. Find solutions to problems with face recognition, camera setup, block screen behavior, and more.

Face Recognition Issues

Not Being Recognized

Symptoms: GuacamoleID doesn't recognize your face, or recognition is inconsistent.

Solutions:

  1. Check Lighting

    • Ensure your face is well-lit from the front
    • Avoid backlighting (bright windows behind you)

  2. Camera Position

    • Position yourself directly in front of the camera
    • Keep your face within 1-2 feet of the camera
    • Ensure nothing obstructs the camera view

  3. Profile Quality

    • Ensure you looked directly at the camera during registration

  4. Appearance Changes

    • Re-register if you've significantly changed your appearance
    • New glasses, facial hair, or hairstyle may affect recognition

False Recognition (Recognizing Wrong Person)

Symptoms: Guacamole unlocks for unauthorized users.

Solutions:

  1. Review and delete any incorrect profiles
  2. Re-register with better lighting conditions
  3. Enable liveness protection
  4. Increase the recognition threshold in settings

Recognition Too Slow

Symptoms: Takes several seconds to recognize and unlock.

Solutions:

  1. Ensure adequate lighting on your face
  2. Check CPU usage - close unnecessary applications
  3. Try reducing camera resolution
  4. Disable unnecessary features to improve performance

Camera Problems

Camera Not Detected

Symptoms: GuacamoleID shows "No camera found" or camera dropdown is empty.

Solutions:

  1. Physical Connection

    • Ensure external cameras are properly connected
    • Try a different USB port
    • Check cable connections

  2. Driver Issues

    • Update camera drivers in Device Manager
    • Reinstall camera drivers
    • Check for Windows updates

  3. Permissions

    • Ensure Guacamole has camera permissions
    • Go to Windows Settings > Privacy > Camera
    • Allow apps to access your camera

  4. Other Applications

    • Close other apps that might be using the camera
    • Restart Guacamole

Camera Shows Black Screen

Symptoms: Camera is selected but preview shows black.

Solutions:

  1. Check if a physical privacy shutter is closed
  2. Try a different camera if available
  3. Restart Guacamole
  4. Check camera in another application to verify it works
  5. Update camera drivers

Depth Camera Not Working

Symptoms: IR camera not available or not providing infrared image.

Solutions:

  1. Hardware Check

    • Verify your device has an IR camera
    • IR cameras are usually separate from RGB cameras
    • Look for a small lens near the main camera

  2. Driver Requirements

    • Install Windows Hello drivers
    • Update Intel RealSense drivers if applicable
    • Check manufacturer's support page

  3. Settings Configuration

    • Enable Depth camera in Guacamole settings
    • Select the correct Depth camera from the dropdown

Virtual Camera Issues

Symptoms: Virtual camera not appearing in other applications.

Solutions:

  1. Ensure virtual camera feature is enabled
  2. Restart the application that needs to use the virtual camera
  3. Check that virtual camera drivers are installed
  4. Verify your subscription tier includes virtual camera

Block Screen Issues

Block Screen Activates Too Frequently

Symptoms: Screen blocks when you're still present.

Solutions:

  1. Adjust Blocking Speed

    • Go to Settings > General
    • Change blocking speed to "Slow" or "Medium"

  2. Improve Detection

    • Ensure good lighting on your face
    • Check camera angle and positioning

Block Screen Won't Activate

Symptoms: Screen doesn't block when you leave.

Solutions:

  1. Verify Guacamole is running (check system tray)
  2. Check that block screen feature is enabled
  3. Ensure camera is functioning and selected

Can't Unlock the Block Screen

Symptoms: Block screen won't recognize you to unlock.

Solutions:

  1. Position Yourself Properly

    • Face the camera directly
    • Ensure adequate lighting

  2. Use Fallback Method

    • Press any key to go to Windows lock screen
    • Log in with Windows password

  3. If Completely Locked Out

    • Restart the computer
    • Log in with Windows credentials
    • Re-register your face profile

Application Issues

Guacamole Won't Start

Symptoms: Application doesn't launch or crashes on startup.

Solutions:

  1. Run as Administrator

    • Right-click Guacamole
    • Select "Run as administrator"

  2. Check System Requirements

    • Verify your system meets minimum requirements
    • Update graphics drivers
    • Ensure Windows is up to date

  3. Reinstall Application

    • Uninstall Guacamole
    • Download latest version
    • Install fresh

  4. Check Logs

    • Contact support with log files

High CPU Usage

Symptoms: GuacamoleID using excessive CPU resources.

Solutions:

  1. Enable power saver mode
  2. Reduce camera resolution
  3. Close unnecessary background applications
  4. Update to the latest version

Application Freezing

Symptoms: GuacamoleID becomes unresponsive.

Solutions:

  1. Wait a few seconds - it may be processing
  2. Force close via Task Manager
  3. Restart the application
  4. Check for conflicting software
  5. Update graphics and camera drivers

Account & Subscription Issues

Can't Log In to Account

Symptoms: Unable to sign in to your Guacamole account.

Solutions:

  1. Verify email and password are correct
  2. Use "Forgot Password" to reset password
  3. Check internet connection
  4. Try logging in via web portal first
  5. Contact support if account is locked

Subscription Not Recognized

Symptoms: App shows free tier despite having subscription.

Solutions:

  1. Sign out and sign back in
  2. Check subscription status in web portal
  3. Verify payment method is valid
  4. Contact support if payment was processed

Features Missing

Symptoms: Expected features not available in the application.

Solutions:

  1. Verify your subscription tier includes the feature
  2. Update to the latest version
  3. Sign out and sign back in

Sync & Cloud Issues

Profiles Not Syncing

Symptoms: Face profiles not appearing on other devices.

Solutions:

  1. Check Sync Settings

    • Ensure biometric sync is enabled
    • Go to Settings > Account > Biometric Sync

  2. Verify Account

    • Confirm you're signed into the same account
    • Check internet connection

  3. Manual Sync

    • Try triggering a manual sync from settings
    • Wait a few minutes for sync to complete

Performance Optimization

Improving Battery Life

  1. Enable Power Saver mode (Eco or Custom)
  2. Set shorter inactivity timeouts
  3. Enable "Turn Off AI and Cameras" on inactivity

Reducing Resource Usage

  1. Disable features you don't use
  2. Enable power saving mode
  3. Close unnecessary background applications

Improving Recognition Speed

  1. Ensure good lighting
  2. Keep face profiles up to date
  3. Disable liveness for faster (but less secure) recognition

Getting Help

Collecting Diagnostic Information

When contacting support, gather:

  1. Application version (Settings > About)
  2. Operating system and version
  3. Camera model and driver version
  4. Description of the issue
  5. Steps to reproduce the problem
  6. Any error messages displayed

Contacting Support

  • Email: support@guacamole.ai
  • Web Portal: Submit a ticket via the support section
  • Knowledge Base: Check online documentation first

Reporting Bugs

  1. Document the exact steps to reproduce
  2. Note any error messages
  3. Submit via the feedback option in the app