Platform admin troubleshooting

Diagnose silent automation, dead email, the academic-year invariant, and the role changes that do nothing - with the environment variable or record behind each.

Getting started guide for day and boarding schools.

Last updated August 29, 2026

Platform-level faults fall into three families. Something is missing from the environment, which produces failures that are total rather than partial. Something is missing from the school spine - an active academic year, a homeroom teacher, a calendar sync - which produces failures that follow the record. Or somebody is on the wrong role, which produces failures that follow the person. Establish which family you are in before changing anything, because the three are fixed by an operations engineer, an administrator, and a Platform Admin respectively.

Telling a permission problem from a configuration problem

The reliable test is to reproduce the problem as a Platform Admin. That role bypasses nearly every access check in the product, so if it reproduces, the cause is data or environment and no amount of role editing will move it. If it does not reproduce, look at the reporter’s role name rather than at any permission screen. Two further signals help. Missing navigation entries are almost always permission, because the sidebar is built from role capability rather than from data. Screens that load but stay empty are almost always configuration. And remember that a few capabilities do not follow the role at all: admissions follows Admissions committee membership, exam coordination follows Examination committee membership, and the library desk follows the staffType field on the employment record.

Symptom	Cause	Fix
No email anywhere in the product	Incomplete SMTP configuration	SMTP_HOST, SMTP_PORT, SMTP_USER, and SMTP_PASS are all required. The mail transport is built when the module loads, so a missing value makes every send throw rather than degrade. Confirm at /settings/email-test.
Repeated sign-outs and 401 responses	NEXTAUTH_URL does not match the browser origin	Set it to the exact public HTTPS address, along with NEXT_PUBLIC_SITE_URL, and restart.
Attendance denominators look wrong	The calendar was not re-synced after a holiday change	Add the holiday at /holiday-master, then re-sync /academic-calendar. Note that percentages are marks over marks, so a re-sync corrects working-day counts, not the percentage.
A new staff account can sign in but sees almost nothing	The role does not map to an account type	Only Teacher, Principal, Vice Principal, Support Staff roles, Student, and Platform Admin produce an account type. Anything else leaves the user typeless and invisible to staff pickers.
Online payment returns a server error	Payment mode and provider keys	FEES_ONLINE_PAYMENT_MODE accepts simulated, razorpay, stripe, telr, or disabled, and defaults to disabled. A live mode without keys fails at the gateway call.
An account cannot sign in at all	The user record is inactive	Reactivate at /users. Deactivating a student does not deactivate their guardian records, which have to be handled separately at /parents.

Screens worth knowing

/activity-log - Platform Admin, Principal, Vice Principal, and the office Admin role see everything; other staff see a scoped view; families and vendors see none. A separate machine feed authenticates with ACTIVITY_SIEM_EXPORT_SECRET rather than a session.
/settings/data-quality - orphan and duplicate checks, open to Platform Admin, Principal, Vice Principal, and the office Admin role.
/reports - Platform Admin, Principal, Vice Principal, and Support Staff - Finance only. The office Admin role has no access here, and finance may generate only the fee and finance reports.
/users and /roles - Platform Admin only at both the page and the API.
/settings/seed - never run the full demo seed against live data.
/ops - job heartbeats and the notification dead-letter queue, whose retry action only reschedules the record rather than resending it.

Common questions

Quick answers in plain language.

Nothing automated is running. What exactly does the daily job do?+

scripts/run-school-cron.sh is the only scheduler, and it is not installed for this school. One run posts fee autopay, the fee dunning ladder, homework due reminders, scheduled notice publishing, transport and conversation retention purges, library reservation expiry, the activity-log retention purge, the activity-chain verification, and the observability alert evaluation. With ADMISSIONS_CRON_SECRET set it also expires admission offers. Without FEES_CRON_SECRET or a session cookie the script exits before calling anything at all.

Editing a role at /roles changed nothing. Is the permission model broken?+

No, but it is not what the screen implies. Access decisions throughout the application read the role name, and the permissions column on the role record is an unused JSON field that nothing consults. /roles manages the name, the description, and whether the role is active. To change what somebody can do, change which role their user account holds at /users.

Fee generation started failing with a 409 across the whole school. What causes that?+

More than one academic year marked current. Fee instance generation asserts a single current year and refuses rather than guessing, returning the count it found. Fix the years at /academic-year and rerun. The same invariant sits behind several other year-scoped operations, so it is worth checking first whenever something school-wide breaks at once.

Why did historic page-view entries disappear from the activity log?+

The retention purge deletes read telemetry first - anything with a VIEW or READ action, or a GET or HEAD method - regardless of age, and then deletes remaining rows older than the hot window, which is ninety days unless ACTIVITY_LOG_HOT_DAYS says otherwise. Mutation and financial audit rows inside the window are kept. If you need page views retained, do not schedule that job.

Telling a permission problem from a configuration problem

Screens worth knowing

Common questions

Related searches