9. Troubleshooting, Common Bottlenecks & Frequently Asked Questions

This guide addresses real-world issues educators may encounter while using Shikshak, including low bandwidth, power outages, and formatting inquiries.

1. Dropped Connection or Electricity Load Shedding

Scenario: You clicked "Generate Lesson Plan" or "Generate Exam Paper", but before it finished, the electricity cut out or your mobile data dropped.

What Happens:

• Shikshak is engineered with Session Independence (AC-04). AI generation runs on our cloud servers independently of your phone or computer connection.
• Your work is NOT lost: The server completes the generation and automatically saves the finished document into your My Plans library (/my).
• No credit is wasted: When your internet reconnects, simply open /my to view, edit, or download your completed plan.
• Instant Abort & Credit Refund Option: If your network connection drops or generation stalls, the screen alerts you of disconnection and offers an "Abort & Refund Credits / रद्द गरी क्रेडिट तुरुन्त फिर्ता लिनुहोस्" action to cancel the pending request immediately and restore deducted credits to your profile. If generation ever takes longer than expected (35+ seconds), a courteous option appears allowing you to cancel and refund your credits at any time.

2. "Generation Took Too Long" (Provider Timeout) & Platform Service Maintenance

Scenario A — Temporary Slowdown / Provider Timeout:

The progress bar pauses and displays a message stating: *"AI generation request timed out (GENERATION_PROVIDER_TIMEOUT). Your credits have been automatically refunded. Please try generating again."*

• Cause & Solution: During peak hours (e.g. Sunday mornings before school starts or terminal exam weeks), large model requests may occasionally exceed the timeout ceiling.
• Your credits are safe: The system marks this as a transient failure and your credit balance is automatically restored.
• Action: Click the "Try Again" button on screen. Second attempts typically resolve in under 15 seconds.

Scenario B — Platform Service Maintenance (`PROVIDER_QUOTA_EXHAUSTED`):

The screen displays: *"AI generation service is temporarily undergoing platform maintenance. Your credits have been safely refunded. Please try again later or contact support."* (नेपाली: *"एआई उत्पादन सेवा हाल प्राविधिक मर्मत तथा अद्यावधिकमा छ। तपाईंको क्रेडिट सुरक्षित रूपमा फिर्ता गरिएको छ।"*)

• Cause: Upstream AI engine capacity or service pipelines are undergoing brief system maintenance.
• Zero Credit Loss Guarantee: Deducted credits are immediately and automatically refunded back to your profile. You lose zero credits.
• Automated Alerting: Our technical team and engineering monitors are automatically and instantly alerted the moment this occurs.
• Action: You do not need to repeatedly retry. Simply wait a brief period, explore existing documents in My Library (`/my`), or contact our support team via WhatsApp or /help if you have an urgent class deadline.

3. "Too Many Pages Just Now" (Rate Limiting)

Scenario: An error message displays: *"Too many pages just now. Please wait a little and try again."*

Cause:

• To prevent abuse and ensure server stability for all schools, Shikshak enforces a rate limit (up to 40 generations per hour per shared staffroom IP address).
• In a busy staff room where 10 teachers share one Wi-Fi router, multiple simultaneous generations may occasionally trigger this temporary guardrail.
• Action: Wait 3 to 5 minutes before submitting another request, or switch your device briefly to mobile data hotspot.

4. Student Name Flagged / Privacy Notice

Scenario: When creating report card remarks or rubrics, you receive a notice stating student names cannot be processed, or the name is replaced with a placeholder like Roll #.

Cause:

• Under strict child privacy regulations (FR-PRIV-05), Shikshak scans inputs and prevents minors' identifying names from being stored or transmitted.
• Solution: Rephrase your input using:
• *Roll 1* or *Roll 15*
• Student initials like *R.K.* or *S.T.*
• Generic pronouns (*"विद्यार्थीले कक्षामा...", "The student shows great improvement in..."*)

5. File Upload Size Limits & Compression

• Textbook PDFs (`/curriculum/new`): Maximum file size is 32 MB. If your scanned textbook PDF exceeds 32 MB, use a free online PDF compressor (or select "Compress PDF" on your phone) before uploading.

6. Devanagari Characters Displaying as Boxes in Microsoft Word

Scenario: You downloaded a .docx file, and some Nepali headings appear with broken letters or rectangular boxes (tofu boxes).

Cause & Solution:

• Your computer may lack modern Unicode Devanagari fonts.
• Solution: Select all text in Word (Ctrl+A) and change the font family to Kalimati (कालिमाटी), Noto Sans Devanagari, or Mangal.
• Important: Never change the font to Preeti or Kantipur — these are legacy ASCII fonts that will corrupt the Unicode characters.

7. Fonepay QR Payment Pending

Scenario: You paid by Fonepay QR, but your credit balance did not update immediately.

Solution:

• Fonepay QR payments are checked by our team from your uploaded screenshot, usually within a few hours.
• Make sure you uploaded the screenshot on the checkout page and that the amount matches your order.
• If credits do not appear within a day, contact our support team with your transaction reference ID.

8. Email Verification Link Issues or "Link Expired"

Scenario: You registered with email and password, received the verification email, and clicked the link, but saw a notice stating the link was invalid or already expired.

Cause & Resolution:

• Why it happens: Modern email services (such as Gmail or corporate mail servers) and browser security filters occasionally pre-scan links to protect you from malware. This pre-scan confirms your email token in Supabase before your browser tab finishes loading, marking the single-use token as consumed.
• Your account is already verified! When this happens, your account has already been successfully confirmed in the system.
• Action:

• Missing verification email? Check your Spam or Junk folder. You can also click "Resend confirmation email" on the signup confirmation screen.
• Fast alternative: You can also use 1-Click Google Sign-In anytime with the same Gmail address without needing any password.

9. Password Reset Recovery Link & "Link Expired" Notice

Scenario: You requested a password recovery link via "Forgot password?" (/forgot-password), received the email in Gmail/Outlook, clicked the link, and saw a message stating the recovery link has expired or has already been used.

Cause & Resolution:

• Why it happens: Password recovery tokens are strictly single-use security tokens. If an email security scanner or antivirus tool pre-fetches the link to inspect it, or if the link is clicked multiple times, the one-time token is safely retired to prevent unauthorized access.
• Dedicated Set New Password Screen (`/reset-password`): Clicking an active recovery link takes you directly to the Set New Password screen (/reset-password). You do not need to know or enter your old password; simply enter your new 8+ character password and confirm it.
• Action if expired:

10. Custom Template File Cannot Be Read

Scenario: You chose Custom Template File (आफ्नै ढाँचाको फाइल) for a lesson plan or a question paper, uploaded a document, and the card said it could not be read.

Cause & Solution — pick the one that matches your error:

• "No readable text was found in that file" — the file is a scan or an image with no text behind it. Open it on your computer, copy the headings and labels into a fresh Word document, and upload that. Or upload a digital (not scanned) PDF.
• "No section/mark breakdown could be found in that file" (question papers only) — your file is readable, but Shikshak could not find the groups and marks in it. Upload the answer half of your paper as well as the question half, or upload the paper a teacher would actually hand out. If you would rather not upload anything, set the groups yourself using the form's section builder.
• "This looks like Preeti legacy-font text" — the Word file was typed with the old Preeti keyboard/font, which stores Nepali as plain ASCII. Re-save it in Unicode Devanagari (Nepali Unicode / Preeti–Unicode converter), or upload the PDF version instead.
• "That file is 12.3MB. The limit is 8MB." — a lesson plan or paper format is one or two pages, so a very large file is usually a scan saved at high resolution. Re-save or compress it, or remove embedded photos and upload again.
• "Reading your format..." never finishes — a scanned PDF is read page by page and genuinely takes longer than a Word file. Wait for it. If it takes more than about a minute, upload the Word version instead.
• The file opened fine on your computer but we cannot read it — try Save As a fresh copy and upload that. This is the fix for most "works on my machine" cases.
• "Your file was read, but the format could not be saved" — The file extraction was successful. Shikshak automatically preserves the analyzed template in a resilient edge cache, allowing you to proceed with generating your lesson plan or question paper immediately without interruption.

Nothing is lost: no credit is spent, and no half-read format is saved. Nothing is generated until a file has been read successfully.

11. Staying Signed In & Automatic Session Refresh

How Shikshak Keeps You Logged In:

• Shikshak issues 30-day persistent sessions using secure HTTP-only cookies (shikshak_teacher_session and shikshak_teacher_refresh).
• Seamless Token Refresh: Standard security tokens refresh in the background automatically as you use the application or generate documents. You will not be randomly logged out during lesson planning or exam preparation.
• Returning to Shikshak: When you open your browser or phone app days later, your session is automatically re-validated and refreshed without requiring you to re-enter your password or Google credentials.
• One-Time Upgrade Notice: If you previously had an older browser session that lacked a refresh token, signing in once via Google or your email/password establishes the 30-day auto-refresh credentials for your device.
• Logging Out Securely: To sign out of a shared school staffroom computer, always click your avatar in the top navigation bar and select Sign Out (लगआउट) to clear all session cookies.

12. Camera Access, Permissions & Troubleshooting in 'Take Photo' Viewfinder

Scenario: When clicking "Take Photo (फोटो खिच्नुहोस्)" to capture a textbook page or notes, the camera viewfinder displays: *"Camera permission was denied or blocked in your browser or operating system"* or fails to start.

Cause & Step-by-Step Resolution:

• Look at the left side of your browser's address bar (near the web address).
• Click the Lock icon (🔒) or Site Settings (🎚️) icon.
• Change the Camera setting from *"Block"* to *"Allow"*, then click "Retry Camera (पुनः प्रयास गर्नुहोस्)" inside the modal.

• If browser permissions are already set to "Allow" but the camera still cannot open, Windows OS privacy may be blocking your browser app.
• Click Start → Settings → Privacy & security → Camera.
• Make sure "Camera access" is switched ON.
• Scroll down to "Let desktop apps access your camera" and ensure it is switched ON (so Chrome, Edge, or Firefox have system permission).

• Open System Settings → Privacy & Security → Camera.
• Ensure the toggle next to your web browser (Chrome, Safari, Firefox, or Brave) is enabled.

• If your laptop or desktop lacks a webcam or the camera hardware is in use by another video call, simply click "Upload Files Instead" inside the warning banner.
• You can instantly select photos (JPG/PNG) or digital PDFs from your computer files with zero setup required.

• On mobile smartphones, tap "Open Phone Camera (फोन क्यामेरा खोल्नुहोस्)" inside the modal to capture photos directly using your phone's native camera app with autofocus and flash.

13. Official Support Channels & Office Location

If you need direct human assistance, custom school onboarding, or billing resolution:

• Support Email: shikshak.ai2026@gmail.com
• Phone & Viber / WhatsApp: +977 9743261607 (Sun–Fri, 9:00 AM – 6:00 PM NPT)
• Support Desk & Inquiries: Shikshak Support Desk, Nepal
• Live Assistant: Open Shikshak AI on any screen (tap the sparkle icon in the bottom right corner).