Troubleshooting Guide

Solutions to common issues and problems

Published

November 20, 2025

Overview

This guide provides solutions to the most common issues encountered when using Kai the AI. Issues are organized by category for quick reference.

TipQuick Diagnosis

Most issues fall into one of these categories: - Connection: API keys, network, LMS integration - Mobile App: Notifications, enrollment, sync issues - Features: Feedback, quizzes, analytics not working - Performance: Slow response, timeouts, data lag

Connection Issues

API Key Errors

“Invalid API Key” or “Authentication Failed”

Symptoms: - Cannot connect to Kai services - 401 Unauthorized errors - Integration tests fail

Solutions:

  1. Verify API Key:

    # Check for common issues:
- Extra spaces at beginning/end
- Incomplete copy (key should start with "kai_")
- Wrong key type (using test key in production)

  2. Regenerate Key:

    • Dashboard → Settings → API Keys
    • Click “Regenerate Key”
    • Update in all integration points
    • Wait 5 minutes for propagation

  3. Check Key Permissions:

    • Ensure key has required scopes
    • Verify not expired
    • Confirm account status is active

“API Key Limit Exceeded”

Symptoms: - 429 Too Many Requests errors - Features stop working sporadically

Solutions:

  1. Check Usage:
    • Dashboard → Analytics → API Usage
    • Review current plan limits
    • Identify usage spikes
  2. Optimize Requests:
    • Reduce feedback request frequency
    • Implement client-side caching
    • Batch API calls where possible
  3. Upgrade Plan:
    • Contact sales@chi2labs.com
    • Consider institution license for higher limits

LMS Integration Issues

Canvas Integration Not Syncing

Symptoms: - Courses not appearing in Kai - Assignments not syncing - Grade updates not pushing back

Diagnostic Steps:

# Test connection
Dashboard → Integrations → Canvas → Test Connection

# Check logs
Dashboard → Integrations → Canvas → View Logs

Solutions:

  1. Verify LTI Configuration:
    • Client ID matches in both systems
    • Redirect URIs exactly match
    • JWK URL accessible from Canvas servers
  2. Check Canvas Permissions:
    • Admin → Settings → Apps → Kai
    • Ensure all required permissions granted
    • Re-authorize if needed
  3. Test Individual Components:
    • Launch LTI tool from Canvas
    • Check if courses appear
    • Verify user mapping
  1. Verify Access Token:
    • Token not expired
    • Has required scopes:
      • url:GET|/api/v1/courses
      • url:POST|/api/v1/courses/:course_id/assignments
      • url:PUT|/api/v1/courses/:course_id/assignments/:id/submissions/:user_id
  2. Check Network Access:
    • Kai can reach Canvas API endpoint
    • No firewall blocking
    • HTTPS properly configured
  3. Review Rate Limits:
    • Canvas API rate limits not exceeded
    • Implement exponential backoff
    • Contact Canvas admin if needed

Blackboard Integration Issues

Common Issues:

  1. Building Block Not Installing:

    Error: "Incompatible with current Blackboard version"
Solution: Download version-specific .war file from Kai dashboard

  2. Features Not Appearing:

    Error: Building block installed but no Kai features visible
Solution:
- System Admin → Building Blocks → Kai → Set to Available
- Clear Blackboard cache
- Wait 5-10 minutes for propagation

  3. Grade Sync Failing:

    Error: Grades not appearing in Blackboard gradebook
Solution:
- Verify grade column exists in Blackboard
- Check Kai has write permissions
- Review Blackboard logs: System Admin → Logs → Filter "Kai"

Moodle Integration Issues

Plugin Not Recognized:

  1. Installation Path: Ensure plugin installed to correct directory

    Correct: /path/to/moodle/local/kai/
Incorrect: /path/to/moodle/kai/

  2. Permissions: Set proper file permissions

    chmod -R 755 /path/to/moodle/local/kai/
chown -R www-data:www-data /path/to/moodle/local/kai/

  3. Database Update: Manually trigger update

    Site Administration → Notifications → Update Database Now

Mobile App Issues

Notifications Not Working

Students Not Receiving Push Notifications

Systematic Diagnosis:

  1. Device Settings:

    iOS: Settings → Notifications → Kai Student → Allow Notifications
Android: Settings → Apps → Kai Student → Notifications → Enabled

  2. App Settings:

    Open Kai app → Settings → Notifications → Feedback Requests: ON

  3. Network Issues:

    • Ensure device has internet connection
    • Check if other apps receive notifications
    • Try WiFi vs. cellular data

  4. Server-Side Check:

    Dashboard → Course → Students → [Student Name] → Notification Status
Should show: "Last notification delivered: [timestamp]"

Solutions by Platform:

Do Not Disturb / Focus Mode:

Settings → Focus → [Current Mode] → Apps → Kai → Allow

Notification Summary:

Settings → Notifications → Scheduled Summary
Ensure Kai is NOT in scheduled summary (needs immediate delivery)

Reset Notifications:

1. Delete Kai app
2. Restart device
3. Reinstall Kai
4. Grant notification permission
5. Re-enroll in course

Battery Optimization:

Settings → Apps → Kai Student → Battery → Don't optimize

Data Saver:

Settings → Network & Internet → Data Saver → OFF
Or: Allow Kai to use data when Data Saver is on

Notification Channels:

Settings → Apps → Kai Student → Notifications
Enable ALL channels, especially "Feedback Requests"

Enrollment Issues

Students Can’t Enroll in Course

Error: “Invalid Enrollment Code”

Solutions:

  1. Verify Code:

    • Check for typos (0 vs O, 1 vs l)
    • Confirm code hasn’t expired
    • Ensure using current semester code

  2. Regenerate Code:

    Dashboard → Course → Settings → Enrollment → Regenerate Code

  3. Use Direct Link Instead:

    Dashboard → Course → Settings → Enrollment → Copy Link
Share link directly with students

Error: “Course Not Found”

Solutions:

  1. Publish Course:

    Dashboard → Course → Settings → Status → Published

  2. Check Enrollment Period:

    Dashboard → Course → Settings → Enrollment Window
Adjust start/end dates if needed

App Won’t Sync Course Data

Symptoms: - Course appears empty - Assignments missing - Outdated information

Solutions:

  1. Manual Sync:

    Pull down on course list to refresh
Or: Settings → Sync → Sync Now

  2. Clear Cache:

    Settings → Storage → Clear Cache
(Does NOT delete enrollment or data)

  3. Re-enrollment:

    Settings → Courses → [Course] → Unenroll
Re-enroll using enrollment code/link

Feature Issues

Feedback Workflow Not Working

No Feedback Requests Appearing

Instructor Side:

  1. Verify Feature Enabled:

    Dashboard → Course → Settings → Workflows → Feedback: ON

  2. Check Student Enrollment:

    Dashboard → Course → Students → View Enrolled
Should show student count > 0

  3. Test with Dummy Account:

    Create test student account
Enroll in course
Request feedback
Check test account receives it

Student Side:

  1. Verify App Installation:

    Correct app: "Kai Student" (not "Kai Instructor")
Latest version installed

  2. Check Course Enrollment:

    Open app → Courses tab
Course should appear in list

  3. Notification Settings:

    App → Settings → Notifications → Enabled

Low Response Rates (<40%)

Diagnosis:

  1. Check Notification Delivery Rate:

    Dashboard → Analytics → Engagement → Notification Delivery
If <80%: notification issue
If >80%: engagement issue

  2. Survey Students:

    Quick poll: "Why don't you always respond to feedback requests?"
Common answers:
- Didn't see notification
- Too busy during class
- Forgot to enable notifications
- Don't understand the purpose

Solutions:

Cause Solution
Technical issues Address notification problems (see above)
Time pressure Increase response window (3-5 minutes)
Lack of motivation Demonstrate value, show impact
Confusion Re-explain purpose and privacy

Pop Quiz Issues

Quiz Questions Not Generating

Error Messages:

"Insufficient content for quiz generation"
Solution: Provide more course materials or select broader topic
"Topic not recognized"
Solution: Use more specific or standard terminology
"Generation timeout"
Solution: Reduce question count or simplify topic

Diagnostic Steps:

  1. Check Content Library:

    Dashboard → Course → Content → Verify uploads
Need: sylllabus, readings, or lecture notes

  2. Verify Topic Alignment:

    Topic must match content in library
Example: Don't ask about "Regression" if only "Statistics" uploaded

  3. Test with Sample Topic:

    Use pre-loaded topic: "Introduction to [Your Subject]"
If works: content issue
If fails: system issue (contact support)

Students See Different Quiz Versions

This is normal: Kai adapts difficulty based on student performance.

If unintended:

Dashboard → Quiz → Settings → Adaptive Difficulty → OFF
Enable "Same quiz for all students"

Analytics Dashboard Issues

Data Not Updating

Symptoms: - Dashboard shows old data - Recent feedback not appearing - Student counts incorrect

Solutions:

  1. Check Data Freshness:

    Dashboard → Analytics → Last Updated: [timestamp]
If >15 minutes old, force refresh

  2. Force Refresh:

    Click refresh icon (🔄) in top right
Or: Clear browser cache and reload

  3. Verify Data Pipeline:

    Dashboard → System Status → Data Pipeline: Should be "Healthy"
If degraded: wait 30 minutes and retry

Export Failing

Error: “Export timeout” or “File too large”

Solutions:

  1. Reduce Date Range:

    Instead of: Full semester
Try: One month at a time

  2. Filter Data:

    Export specific metrics instead of "All data"

  3. Alternative Export Methods:

    Use API for programmatic access
Or: Request bulk export from support

Performance Issues

Slow Response Times

Dashboard Loading Slowly

Quick Fixes:

  1. Browser Cache:

    Chrome: Ctrl+Shift+Delete → Clear cache
Firefox: Ctrl+Shift+Delete → Clear cache
Safari: Cmd+Option+E

  2. Disable Browser Extensions:

    Try incognito/private mode
If faster: browser extension conflict

  3. Check Internet Speed:

    Visit fast.com or speedtest.net
Need: >5 Mbps download for smooth experience

Long-term Solutions:

  1. Optimize Data Views:

    Dashboard → Settings → Performance
Enable: "Lazy load analytics"
Enable: "Reduce animation"

  2. Archive Old Courses:

    Dashboard → Courses → [Old Course] → Archive
Reduces dashboard load

API Requests Timing Out

Symptoms: - 504 Gateway Timeout errors - Requests taking >30 seconds - Features fail sporadically

Solutions:

  1. Check System Status:

    Visit: status.chi2labs.com
If incident: wait for resolution
If operational: proceed to next step

  2. Reduce Payload Size:

    Instead of: Batch uploading 100 assignments
Try: Upload 10 at a time

  3. Implement Retry Logic:

    // Example for developers
async function callKaiAPI(endpoint, data, retries = 3) {
  try {
    return await fetch(endpoint, { body: data });
  } catch (error) {
    if (retries > 0) {
      await sleep(1000 * (4 - retries)); // exponential backoff
      return callKaiAPI(endpoint, data, retries - 1);
    }
    throw error;
  }
}

Error Messages

Common Error Codes

Error Code Meaning Solution
400 Bad Request Check request parameters
401 Unauthorized Verify API key
403 Forbidden Check account permissions
404 Not Found Verify resource ID
429 Rate Limited Wait and retry, or upgrade plan
500 Server Error Contact support
503 Service Unavailable Check status.chi2labs.com
504 Gateway Timeout Reduce request size or retry

Error Message Decoder

“FEATURE_NOT_ENABLED”

Cause: Trying to use feature not in your plan
Solution: Upgrade plan or disable feature

“STUDENT_LIMIT_EXCEEDED”

Cause: More students enrolled than plan allows
Solution: Upgrade plan or remove inactive students

“INVALID_COURSE_ID”

Cause: Course ID doesn't exist or wrong format
Solution: Verify course ID from dashboard

“WEBHOOK_DELIVERY_FAILED”

Cause: Your webhook endpoint not responding
Solution: Check endpoint URL, ensure publicly accessible

Platform-Specific Issues

Browser Compatibility

Recommended Browsers: - ✅ Chrome 90+ (best performance) - ✅ Firefox 88+ - ✅ Safari 14+ - ✅ Edge 90+ - ❌ Internet Explorer (not supported)

If using unsupported browser:

Warning message will appear
Solution: Upgrade to supported browser

Mobile OS Requirements

Minimum Versions: - iOS: 13.0+ - Android: 8.0 (API level 26)+

If on older version:

App won't install from App Store/Play Store
Solution: Update OS or use web interface

Getting Additional Help

Self-Service Resources

  1. Knowledge Base: help.chi2labs.com
  2. Video Tutorials: youtube.com/@KaiTheAI
  3. Community Forum: community.chi2labs.com
  4. System Status: status.chi2labs.com

Contact Support

Support Tiers

Free & Educator Plans: - 📧 Email: support@chi2labs.com - ⏱️ Response time: 24-48 hours - 💬 Community forum support

Institution Plans: - 📧 Email: priority@chi2labs.com - ⏱️ Response time: 2-4 hours - 💬 Dedicated Slack channel - 📞 Phone: 1-800-KAI-HELP - 🎥 Video call support

What to Include in Support Requests

Essential Information:

1. Issue Description:
   - What were you trying to do?
   - What happened instead?
   - Error message (exact text or screenshot)

2. Environment:
   - Browser/App version
   - Operating system
   - Account type (educator/institution)

3. Steps to Reproduce:
   - Step-by-step instructions
   - Expected vs. actual result

4. Impact:
   - How many users affected?
   - Is it blocking critical work?

5. What You've Tried:
   - Troubleshooting steps already attempted
   - Any temporary workarounds found

Example Good Support Request:

Subject: Students not receiving feedback notifications on iOS

Description:
I requested feedback at 2:30 PM EST today. 25 out of 30 students
have iOS devices. None of them received the push notification,
but the 5 Android students did receive it.

Environment:
- Course: PSYCH 101, Section 03
- iOS versions: mostly 15.x and 16.x
- Kai Student app version: 2.4.1

Steps to Reproduce:
1. Open Kai Instructor app
2. Tap "Request Feedback"
3. Wait 2 minutes
4. iOS students show no notification

Impact:
- High: Cannot use feedback workflow
- Affects 80% of my students

Already Tried:
- Verified students have notifications enabled
- Tested with my own iOS device (same issue)
- Checked system status (all green)
- Android students working fine

Request: Please investigate iOS notification delivery issue.

Reporting Bugs

Bug Report Template:

1. Bug summary (one sentence)
2. Expected behavior
3. Actual behavior
4. Steps to reproduce
5. Screenshots/videos (if applicable)
6. Environment details
7. Frequency (always/sometimes/once)

Submit bugs: - 🐛 GitHub: github.com/chi2labs/kai-issues - 📧 Email: bugs@chi2labs.com

Feature Requests

How to Request Features:

1. Check existing requests: community.chi2labs.com/features
2. If new: Create detailed description
3. Include use case and expected benefit
4. Vote on existing requests that matter to you

Popular recent requests: - Integration with Zoom for attendance tracking - Advanced analytics for longitudinal studies - Custom grading rubric templates - Multi-language support

Preventive Maintenance

Regular Health Checks

Weekly: - ✅ Check notification delivery rate (should be >90%) - ✅ Review API usage vs. limits - ✅ Test mobile app connectivity

Monthly: - ✅ Update mobile apps to latest version - ✅ Review and archive old courses - ✅ Audit student enrollment lists - ✅ Check LMS integration status

Semester Start/End: - ✅ Verify all integrations still active - ✅ Update student lists - ✅ Export analytics data for records - ✅ Clean up test data

Backup and Recovery

What’s Automatically Backed Up: - ✅ All course data and analytics - ✅ Student responses and feedback - ✅ Quiz results and grading data - ✅ Configuration settings

What You Should Back Up: - ⚠️ Custom rubrics (export from dashboard) - ⚠️ Integration credentials (store securely) - ⚠️ Custom content libraries

How to Export Data:

Dashboard → Course → Settings → Export
Select: "All data" or specific datasets
Format: CSV, JSON, or PDF

Still stuck? Our support team is here to help. Don’t hesitate to reach out!