Troubleshooting Guide

InspectRAG Troubleshooting Guide 🛠️

This guide helps users and administrators identify and resolve common issues when using InspectRAG. Each section provides potential problems, causes, and solutions to keep the system running smoothly.

Issue: Unable to log in via OpenID

Possible Causes: - Incorrect username or password. - OpenID provider is down or not reachable. - MFA verification step failed.

Solutions: 1. Verify that your username and password are correct. 2. Check your network connection to ensure you can reach the OpenID provider. 3. If MFA is enabled, confirm you completed the verification step properly. 4. Contact your administrator if you suspect the OpenID provider is down.

2. Access Denied for Querying a File ❌

Issue: “You don't have permissions to access the contents of the said file, please contact your administrator to get rights.”

Possible Causes: - Your role, group membership, or username does not match the file permissions. - The document’s permissions have been updated, and your access is no longer valid. - LDAP sync from Active Directory to OpenID failed.

Solutions: 1. Verify with your administrator that your roles and group memberships are up-to-date. 2. Ask the document owner or creator to review the file’s permissions. 3. If roles were recently changed, ask the administrator to force an LDAP sync to update permissions.

3. Webhook or Event Receiver Issues 📁

Issue: SharePoint files are not updating in real-time.

Possible Causes: - Webhook URL for SharePoint Online is unreachable. - Event receivers in SharePoint On-Prem are not working. - Microsoft Graph API permissions are incorrectly configured.

Solutions: 1. Verify Webhook URL: Ensure the webhook endpoint is publicly accessible and working. 2. Check API Permissions: Verify that Sites.Read.All and Sites.Manage.All permissions are correctly granted. 3. Restart Event Receivers: For SharePoint On-Prem, restart the event receivers using PowerShell and test with a sample file update.

4. Files Uploaded via Chat Are Not Queryable 💬

Issue: Uploaded documents are not appearing in queries.

Possible Causes: - The document upload process failed. - VectorDB did not store the file embeddings correctly. - The permissions for the uploaded file are not set properly.

Solutions: 1. Re-upload the document: Make sure the upload process completes successfully. 2. Check Database Connection: Ensure VectorDB is running and connected to InspectRAG. 3. Set Permissions: Verify that the user who uploaded the file has set appropriate access permissions.

5. Incorrect Role Sync from Active Directory (AD) 🧑‍💼

Issue: User roles or group memberships are not reflected in InspectRAG.

Possible Causes: - LDAP sync failed between AD and OpenID. - The AD user or group is not mapped correctly in the OpenID provider.

Solutions: 1. Force an LDAP Sync: Ask the administrator to manually sync roles and users. 2. Verify Role Mapping: Check the mappings in the OpenID provider to ensure they align with AD. 3. Check AD Permissions: Ensure the service account used for LDAP sync has the required permissions.

6. Queries Are Slow or Time Out ⏳

Issue: Querying documents takes too long or fails.

Possible Causes: - VectorDB is overloaded or not optimized. - Too many simultaneous queries are running. - A large number of documents are stored without indexing.

Solutions: 1. Optimize VectorDB: Ensure proper indexing is in place for faster querying. 2. Limit Concurrent Queries: Monitor and limit simultaneous queries if performance degrades. 3. Restart the Database: If VectorDB is overloaded, restarting it may help.

7. User Unable to Access SharePoint Documents 📁

Issue: User receives an access denied message for a SharePoint document.

Possible Causes: - User’s roles and permissions in SharePoint are not aligned with AD. - LDAP sync was not completed. - The document permissions in SharePoint were recently changed.

Solutions: 1. Sync Roles with SharePoint: Ensure that SharePoint permissions reflect AD roles accurately. 2. Re-sync LDAP: Ask the administrator to manually re-sync AD roles to the OpenID provider. 3. Review Document Permissions: Have the document owner or SharePoint admin update permissions if necessary.

8. Audit Logs Are Incomplete or Missing 📋

Issue: Logs for queries or access attempts are not visible.

Possible Causes: - Logging services are disabled or misconfigured. - The system is not recording logs in real-time.

Solutions: 1. Enable Logging: Verify that logging is enabled in the InspectRAG configuration. 2. Check Storage Location: Ensure that the logs are stored in the correct directory or database. 3. Monitor Logging Services: Restart logging services if they have stopped.

9. Notifications for File Changes Are Not Triggered 🔔

Issue: Users are not receiving notifications about document changes.

Possible Causes: - Webhooks or event receivers are not functioning properly. - Notification settings are disabled for the user.

Solutions: 1. Verify Webhook Functionality: Ensure webhooks are configured and reachable. 2. Enable Notifications: Ask the administrator to enable notifications for relevant users. 3. Restart Event Receivers: If using SharePoint On-Prem, restart event receivers to re-enable change tracking.

10. Contacting Support for Help

If the issue persists after trying the solutions above: - Contact your administrator to escalate the problem. - If the issue is related to OpenID or AD sync, reach out to the IT team managing these systems. - For SharePoint-related problems, contact the SharePoint administrator.

This troubleshooting guide ensures that both users and administrators can resolve common issues quickly and keep InspectRAG running smoothly. If further assistance is needed, always escalate to your organization’s IT support team.