Classroom Troubleshooting

This guide outlines exactly what to do when something goes wrong during a live lesson. We have mapped out every potential failure point, from standard network drops to edge-case browser permissions, and provided 1-click or 2-button workflows to resolve them.

🖥️ Live Quiz & Response Issues

1. Student says: "I don't see the active live quiz banner on my screen!"

• What went wrong: The student's dashboard did not receive the real-time polling signal because the client-side fetch interval was interrupted, or they logged in after the poll started.
• The Quick-Fix Workflow:
  1. Have the student refresh their page (F5 or pull-to-refresh on mobile).
  2. If it still doesn't appear, the teacher can click End Quiz Session and relaunch it immediately. This broadcasts a fresh state update to all active web clients.

2. Projector shows: "Responses: 0" (But students claim they submitted)

• What went wrong: The projector modal's status interval has paused, or the student submissions are blocked by local school firewall rules filtering API requests.
• The Quick-Fix Workflow:
  1. Teacher Action: Click the Reveal Live Results button twice to force-refresh the state from the backend database manually.
  2. Audit Action: Open a new browser tab and check if https://api.qrserver.com loads. If the school network blocks this domain, the QR code image will not render, but student submissions will still register if they go directly to the dashboard URL.

📶 WebRTC Co-Working Screen Share Blockers

3. Teacher screen displays: "Connection Timed Out" or "Not Active"

• What went wrong: Peer-to-peer WebRTC connections require a direct network path. Strict school firewalls (Symmetric NATs) often block these UDP ports.
• The Quick-Fix Workflow:
  1. Click 🛑 Stop Screen Share on the teacher dashboard.
  2. Have the student click Refresh on their device.
  3. Click 🖥️ Start Screen Share again. If the firewall continues to block the direct stream, utilize your classroom's standard management tool (e.g., GoGuardian, LanSchool) as a secondary backup stream.

4. Student says: "I clicked Approve, but the screen is just black!"

• What went wrong: The browser is blocking window/screen capture permissions on the student's operating system.
• The Quick-Fix Workflow (Super Easy Student Steps):
  • On Chromebooks/Chrome: Click the Camera/Microphone icon in the browser URL address bar and verify that screen sharing permissions are set to "Allow".
  • On Macbooks: Open System Settings ➔ Privacy & Security ➔ Screen Recording and make sure Chrome/Safari is toggled ON.

📊 Roster & CSV Upload Glitches

5. CSV Upload gives: "Parsing Error: Headers Not Found"

• What went wrong: The school roster spreadsheet uses custom header names (e.g., Mail Address instead of Email, or Firstname without a space).
• The Quick-Fix Workflow:
  1. Open the CSV in Excel or Google Sheets.
  2. Rename the column headers to exactly match: Email and Name (or First Name and Last Name).
  3. Export as a standard .csv format and drop it back into the parser.

6. Student says: "I didn't receive my CSV invitation email!"

• What went wrong: The school district email filter blocks external messages, or the invitation was categorized into the Spam folder.
• The Quick-Fix Workflow:
  1. In the teacher roster table, locate the student's name.
  2. Click 🔗 Copy Invite Link.
  3. Send this link directly to the student via Google Classroom or your school's LMS chat. When they open the link, they bypass the email step and enroll directly.

⏱️ Time-on-Task & Heartbeat Discrepancies

7. Student claims: "I worked for an hour, but it only shows 10 minutes!"

• What went wrong: The student left the tab open in the background while watching YouTube or playing browser games. Our attention-aware engine stops counting when the tab loses focus.
• The Quick-Fix Workflow:
  1. Remind students that they must keep the BeginnerInvestorHub active in the foreground for hours to count.
  2. If a system glitch occurred, teachers can instruct the student to keep the lesson module open and active to catch up. The backend will automatically recalculate compliance milestones during the next evening run.