Troubleshooting Guide

Quick Diagnostic Checklist

Authentication & Access Issues

Problem: 401 Unauthorized Errors

Possible Causes & Solutions

// Check if user is authenticated
const user = await UALS_Auth.getUser();
console.log('Current user:', user);

// If null, redirect to login
if (!user) {
  window.location.href = '/login.html';
}

// ✅ CORRECT
fetch('/api/school/classes', {
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' }
});

// ❌ WRONG - missing credentials
fetch('/api/school/classes', {
  headers: { 'Content-Type': 'application/json' }
});

Problem: 403 Forbidden - Access Denied

Common Scenarios

// Steps for new owner:
1. Open class details modal
2. Click "Show Content Experts"
3. Click "Add Content Expert"
4. Enter expert's email
5. Submit invitation

// Check current login email
const user = await UALS_Auth.getUser();
console.log('Logged in as:', user.email);

// Compare with class data
const classData = await fetch('/api/school/classes', {
  credentials: 'include'
}).then(r => r.json());

const myClass = classData.classes.find(c => c.id === 'class-xxx');
console.log('Owner:', myClass.teacherEmail);
console.log('Experts:', myClass.contentExperts);

// Check user role
const user = await UALS_Auth.getUser();
console.log('User role:', user.role);

// Required roles for class management:
// - 'educator'
// - 'admin'

Content Editing Issues

Problem: Can't Access Content Editor

Debugging Steps

// In browser console:
const user = await UALS_Auth.getUser();
console.log('My email:', user.email);

// Fetch class data
const classData = await fetch(`/api/school/classes`, {
  credentials: 'include'
}).then(r => r.json());

const myClass = classData.classes.find(c => c.id === 'class-xxx');

console.log('Owner:', myClass.teacherEmail);
console.log('Creator:', myClass.creatorEmail);
console.log('Experts:', myClass.contentExperts);

// Your email must be either:
// - myClass.teacherEmail (owner), OR
// - in myClass.contentExperts array

const classOwnerEmail = classData.teacherEmail;
if (classOwnerEmail && userEmail === classOwnerEmail) {
  return true;
}

Problem: Content Edits Not Saving

Possible Causes & Solutions

1. GCS Connection Issue
   • Check CONTENT_CACHE_METHOD=GCS in environment variables
   • Verify GCS bucket name and credentials
   • Check GCS bucket permissions (writer access required)
2. Network Timeout
   • Large content may timeout - break into smaller chunks
   • Check browser Network tab (F12) for failed requests
3. Version Limit Reached
   • Maximum 4 versions per hash - oldest is auto-deleted
   • This is expected behavior, not an error

Problem: Can't See Other Expert's Edits

Solutions

1. Check Active Version

   Expert A may have created a new version without setting it as active. Owner or another expert should set the correct version as active.

2. Refresh Content Cache

   Hard refresh the page (Ctrl+Shift+R on Windows, Cmd+Shift+R on Mac)

3. Different Content Hash

   If config changed, edits may be on a different hash. Check metadata.json in GCS to see which hash was edited.

Ownership Transfer Issues

Problem: Can't Initiate Transfer

Common Causes

1. Not Current Owner
   • Only the current owner (teacherEmail) can initiate transfers
   • Original creator (creatorEmail) cannot transfer unless also current owner
2. Pending Transfer Exists
   • Only one pending transfer allowed at a time
   • Solution: Cancel existing transfer first, then initiate new one
3. Invalid Email Format
   • Ensure new owner email is valid format
   • Email must match a registered UALS teacher account

Problem: New Owner Doesn't See Pending Transfer

Debugging Steps

// New owner checks their login email
const user = await UALS_Auth.getUser();
console.log('Logged in as:', user.email);

// Compare with ownershipTransferPending
const classData = await fetch('/api/school/classes', {
  credentials: 'include'
}).then(r => r.json());

classData.classes.forEach(cls => {
  if (cls.ownershipTransferPending) {
    const pending = JSON.parse(cls.ownershipTransferPending);
    console.log('Transfer pending for:', pending.newOwnerEmail);
  }
});

Problem: Transfer Accepted But Still Can't Access

Solutions

1. Refresh Dashboard

   Hard refresh (Ctrl+Shift+R) or reload the page to update permissions.

2. Check teacherEmail Field

   // Verify class ownership updated
   const classData = await fetch('/api/school/classes', {
     credentials: 'include'
   }).then(r => r.json());
   
   const myClass = classData.classes.find(c => c.id === 'class-xxx');
   console.log('Owner is now:', myClass.teacherEmail);
   
   // Should match your email after acceptance

3. Clear Browser Cache

   Settings → Privacy → Clear browsing data → Cached images and files

Enrollment Code Issues

Problem: Students Can't Enroll with Code

Common Causes

1. Typo in Code
   • Enrollment codes are case-sensitive
   • Format: ENROLL-ABC12345 (8 characters after dash)
   • Solution: Copy-paste the code instead of typing
2. Code Changed
   • Owner may have regenerated the enrollment code
   • Solution: Get updated code from teacher
3. Class Archived
   • Archived classes don't accept new enrollments
   • Solution: Contact class owner to restore class

Problem: Need to Regenerate Enrollment Code

Scenario: Enrollment code was shared publicly by mistake.

await fetch(`/api/school/class/${classId}`, {
  method: 'PATCH',
  credentials: 'include',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    enrollmentCode: 'ENROLL-NEWCODE1'
  })
});

xAPI LRS Connection Issues

Problem: Classes Not Loading

Debugging Steps

// Common error messages:
"Failed to connect to LRS"
"LRS authentication failed"
"xAPI statement retrieval timeout"

LRS_ENDPOINT=https://your-lrs.com/xapi
LRS_USERNAME=your_username
LRS_PASSWORD=your_password

// Run health check
npm run health:quick

// Or test xAPI specifically
npm run test:xapi

// In xapiClient.js, check query filters
const result = await this.getStatements({
  agent: { mbox: `mailto:${userEmail}`, objectType: 'Agent' },
  verb: 'http://adlnet.gov/expapi/verbs/initialized',
  activity: 'https://uals.app/class/',
  related_activities: true
});

// Ensure not using getAllStatements() (deprecated)

Problem: Duplicate Classes Appearing

Root Cause

Multiple xAPI statements exist for the same class ID due to updates. The getAllClasses() function should deduplicate by keeping only the most recent statement per class ID.

Solution

// In schoolData.js, ensure deduplication logic:
const classMap = new Map();
statements.forEach(stmt => {
  const classId = stmt.context.extensions['http://uals.app/class/id'];
  const existing = classMap.get(classId);

  // Keep newest statement
  if (!existing || new Date(stmt.timestamp) > new Date(existing.timestamp)) {
    classMap.set(classId, stmt);
  }
});

const uniqueClasses = Array.from(classMap.values());

Browser-Specific Issues

Safari: Cookie Restrictions

Solution

1. Safari → Preferences → Privacy
2. Uncheck "Prevent cross-site tracking"
3. OR add exception for uals.app domain
4. Refresh UALS dashboard

Chrome: Incognito Mode

Solution

1. Chrome → Settings → Privacy and security → Cookies
2. Select "Allow all cookies" or add exception for uals.app
3. Alternatively, use normal mode instead of incognito

Firefox: Enhanced Tracking Protection

Solution

1. Click shield icon in address bar
2. Toggle "Enhanced Tracking Protection" to OFF for uals.app
3. Refresh page

Developer Debugging Tools

Browser Console Utilities

// Check authentication status
const user = await UALS_Auth.getUser();
console.log('User:', user);

// Fetch all classes
const classes = await fetch('/api/school/classes', {
  credentials: 'include'
}).then(r => r.json());
console.log('Classes:', classes);

// Check specific class ownership
const myClass = classes.classes.find(c => c.id === 'class-xxx');
console.log('Owner:', myClass.teacherEmail);
console.log('Creator:', myClass.creatorEmail);
console.log('Experts:', myClass.contentExperts);

// Verify you can edit
const canEdit = myClass.teacherEmail === user.email ||
                myClass.contentExperts.includes(user.email);
console.log('Can edit:', canEdit);

// Check pending transfers
classes.classes.forEach(c => {
  if (c.ownershipTransferPending) {
    console.log('Pending transfer:', c.id, JSON.parse(c.ownershipTransferPending));
  }
});

Server-Side Debugging

// In canEditClassContent() function:
async function canEditClassContent(userEmail, classId) {
  console.log(`🔍 Permission check: user=${userEmail}, class=${classId}`);

  const classData = await getClassData(classId);
  console.log(`📋 Class data:`, {
    owner: classData.teacherEmail,
    creator: classData.creatorEmail,
    experts: classData.contentExperts
  });

  const isOwner = classData.teacherEmail === userEmail;
  const isExpert = classData.contentExperts?.includes(userEmail);

  console.log(`✅ isOwner=${isOwner}, isExpert=${isExpert}`);

  return isOwner || isExpert;
}

Health Check Commands

# Full health check (LLM, LRS, GCS)
npm run health

# Quick health check
npm run health:quick

# Test specific components
npm run test:xapi
npm run test:gcs
npm run test:openai

Getting Help

Support Channels