Attendance troubleshooting

Fix an empty attendance screen, misleading percentages, missing parent absence alerts, blocked period marking, and rejected CSV imports.

Getting started guide for day and boarding schools.

Last updated August 29, 2026

Nearly every attendance ticket resolves to one of four records: the teacher is not the homeroom teacher of the class, the guardian has no portal user attached, the period slot is not on a published timetable, or the CSV rows do not carry the internal student id. Each section below names the record that has to change and the screen that changes it.

Who can open and save the register

/attendance is a homeroom register. The classes a teacher sees come from the class record fields classTeacherId and coClassTeacherId — not from subject assignments — so a teacher with five periods a week in a class still gets "No class assigned". Platform Admin, Principal, and Vice Principal instead get a picker over every active class. Students are redirected to /my-attendance and parents to /parent-dashboard/attendance, so a family account never reaches the marking screen at all.

Symptom	Cause	Fix
Teacher sees "You are not currently assigned as a class or co-class teacher"	No active class names them as homeroom teacher	Edit the class at /classes and set Class teacher or Co-class teacher. Only Platform Admin, Principal, and Vice Principal can save that change.
Teacher cannot be picked as class teacher	Homeroom eligibility rule	A teacher qualifies if their staffType is PRT, or if they already hold an active subject assignment to that class this year. On a new class, grades 1-5 require PRT and grades 6-12 require PRT, TGT, or PGT.
Subject teacher gets 403 when saving marks	Homeroom-only write gate	POST /api/attendance/bulk allows the class teacher, the co-class teacher, and admins only. Move the homeroom or ask the class teacher to mark.
Register opens but lists no students	No ACTIVE class membership for the active year	Place the students in the section at /students or /classes, and confirm the active year at /academic-year.

Percentages, unmarked days, and reports

Attendance percentage is present marks divided by marks that exist, not by calendar days. A week nobody marked does not appear as absence; it silently shrinks the denominator. Class reports carry a separate unmarkedDays figure for homeroom scope, calculated as working days minus marked days, and the working-day count comes from the academic calendar — holiday days plus the weekend configuration for that year. Syncing the calendar therefore corrects unmarkedDays, not the percentage.

Symptom	Cause	Fix
Percentage looks far too high	Missing registers are not counted as absence	Read unmarkedDays on the class report and chase the days nobody marked; the number will not correct itself.
Working-day count is wrong	Calendar not re-synced after a holiday change	Add the holiday at /holiday-master, then re-sync at /academic-calendar. Weekend rules come from the holiday configuration for the academic year.
Low-attendance list looks empty	Threshold plus minimum sample	The school summary only flags a student below 75 per cent who also has at least five marked days.

Period attendance

/attendance/period is explicitly experimental and sits beside the homeroom register rather than replacing it. The API looks for a PUBLISHED timetable slot for the class, period, and date: with no slot it returns 409 and code PERIOD_NOT_ON_TIMETABLE; with a slot that belongs to someone else it returns 403 and code PERIOD_NOT_ASSIGNED. If a full-day homeroom mark already exists for that student and date, the save is refused with 409 HOMEROOM_CONFLICT so the official register is never rewritten.

Parent absence alerts

Symptom	Cause	Fix
No absence email reached the parent	Guardian record has no portal user	Alerts only reach Parent rows whose userId points at an active user with an email. Create the account at /parents with Create portal and send invite.
In-app alert appeared but no email	SMTP not configured or blocked	Send a test from /settings/email-test. That screen is limited to Platform Admin and the office Admin role.
Correcting a mark sent another alert	Alerts fire on the transition into Absent	Re-saving an already-absent row sends nothing; changing Present to Absent does notify. Fix the roster before the first save when you can.

Bulk CSV import errors

The historical importer is a card on /attendance that appears only in the admin class-picker view and only at desktop width. It handles one class per run and reports per-row failures instead of rejecting the whole file.

Columns are date, studentId, status, and an optional session. Status is PRESENT, ABSENT, or LATE; session is MORNING, AFTERNOON, or FULL_DAY and defaults to FULL_DAY.
studentId is the internal record id, not the admission number or roll number. Use Download template to get a row pre-filled with a real id from the open class.
Every row must belong to an ACTIVE member of the selected class, otherwise the row fails with "Student is not an active member of the selected class".
Valid rows are still saved when other rows fail; export the failures with Download error report, correct them, and re-import.
One request accepts at most 2000 rows, so split a multi-year backfill by month or by term.

Common questions

Quick answers in plain language.

Teacher opens /attendance and sees "No class assigned" — what is missing?+

The register is homeroom-only. It lists classes where the teacher is set as Class teacher or Co-class teacher on the class record, not classes they teach a subject in. A Principal, Vice Principal, or Platform Admin fixes this by editing the class at /classes and setting the Class teacher field.

Why does period attendance return "No published timetable slot for this class, period, and date"?+

POST /api/attendance/period-mark only accepts a mark when a PUBLISHED timetable entry exists for that class, period, and weekday. Publish the grid from /timetable first. Period attendance is experimental and never overwrites the homeroom register — if a full-day mark already exists it returns 409 HOMEROOM_CONFLICT.

Why did a parent not receive the absence email?+

Absence alerts go to Parent rows where userId is set and that user is active with an email address. A guardian record with no portal login gets nothing. Create the login at /parents using Create portal and send invite, and confirm SMTP with /settings/email-test.

Does an approved student leave mark the student absent?+

No. Approving leave at /student-leave records the expected absence but never writes an Attendance row. The daily register at /attendance stays the single source of truth, so the class teacher still has to mark the day.