OneRoster sync

This page covers the OneRoster sync’s common failure modes. For the setup walkthrough, see From OneRoster. For uploaded roster and catalog files, see Imports.

Roster sync lives in the school shell, at School level navigation path: Roster then Sync (the screen: Roster Sync page referenced below). If you see something not on this list, the run detail in screen: History has the failing phase and an error message.

Test connection says the credentials were refused

button: Test connection answered message: The roster source refused these credentials. Check the client ID and secret with your roster admin, then test again.. Lyra reached the roster source, and it turned the client ID and secret away. Likely causes:

Wrong client ID or secret. Re-paste from a fresh copy of what your SIS admin sent. Trailing newlines from a copy-paste through a chat message are easy to miss.
Credentials not yet activated. Some SIS vendors take an hour or so to fully provision new OAuth credentials. If they were issued in the last hour, wait and retry.
Wrong OAuth flow. Lyra requires OAuth 2.0 client credentials. If your SIS only offers OAuth 1.0a, Lyra cannot connect. Use the manual CSV path instead.
Scope mismatch. The OAuth client doesn’t include the required OneRoster scope. Ask your SIS admin to re-issue with the OneRoster scopes enabled.

Test connection says there’s no roster source at the URL

button: Test connection answered message: Lyra could not find a roster source at that base URL. Check the URL and test again.. Lyra never got as far as trying the credentials: nothing answered at that address, or what answered isn’t a OneRoster source. Likely causes:

A typo or a stray character in the path. Lyra trims spaces from either end of the base URL, but a space or extra segment in the middle still sends the request somewhere with nothing there.
Base URL has too much path. The base URL should end at oneroster/v1p1, not oneroster/v1p1/orgs or oneroster/v1p1/users. Trim it back.
IP restriction on the SIS endpoint. Some SIS deployments restrict the OneRoster endpoint to a specific IP range. Lyra’s egress IPs need to be on the allowlist; ask your SIS admin.
Endpoint requires a custom user-agent or header. Rare, but a few SIS deployments require a specific user-agent. Contact support; we can adjust on our side.

First sync ran, but no homerooms appeared

Your SIS doesn’t tag classes as classType: "homeroom". Lyra’s default homeroom picker pre-checks only homeroom-typed classes.

The fix:

On the screen: Roster Sync page, select button: Edit on the setting: Homeroom classes row to re-open the homerooms picker.
Uncheck what isn’t really a homeroom, if anything.
Tick the scheduled or course rows that actually represent homerooms in your SIS.

Sycamore, Gradelink, and some other systems use scheduled for advisory groups rather than homeroom. The pattern is consistent within a SIS; once you’ve picked the right classes once, the next sync uses your selection.

Teachers I expected are missing

Their OneRoster role isn’t one you ticked in step 4. Lyra defaults to importing users with roles teacher, administrator, and aide as faculty. If your principals or other staff have a different role (e.g., proctor), change setting: Faculty roles from the dashboard. The roles you can pick are teacher, administrator, aide, proctor, parent, and guardian.

On the screen: Roster Sync page, select button: Edit on the setting: Faculty roles row.
Tick the roles you want.
Select button: Save.
Select button: Sync now.

A whole sync failed

Open the run in screen: History and read its phase timeline: Authenticate, Fetch users, Fetch classes, Reconcile, and Apply, with the one that failed marked. The error message is under the headline. Enrollments are fetched inside Fetch classes, not as a separate phase.

Failures are atomic: no partial writes happened. The previous sync’s data is still in place.

Under the run’s own next steps are two more links: button: Read the OneRoster troubleshooting guide, and button: Email support, which opens a message already carrying the run’s id and its error message.

Common causes:

Credentials rotated on the SIS side without being mirrored to Lyra. On the screen: Roster Sync page, select button: Edit on the setting: Credentials row.
A schema change on the SIS side. A SIS upgrade can change a required field’s shape. Email support; we’ll adjust the parser.
Rate limit on the SIS side. A high-volume school running multiple integrations on the same SIS tenant may trip a rate limit. Reschedule Lyra’s sync time to avoid overlap.

Duplicate patrons after the first sync

The most likely cause: a patron’s sourcedId (which maps to the patron’s identifier in Lyra) changed between when they were originally imported (via CSV or a prior sync) and the current run. Lyra matches by that identifier; a changed one produces a new patron alongside the old.

Two paths:

Reverse the identifier change in your SIS if possible. Future syncs match the original and the duplicate stops being created.
Contact support for cleanup. Merging duplicates produced by an identifier change is not self-service; we’ll merge on our side.

The prevention rule is the same as for an uploaded roster: don’t change identifiers between syncs. The From OneRoster page has a callout about this.

Homeroom counts look right, but assignments are wrong

Lyra preserves multi-teacher homerooms: every teacher enrollment from OneRoster is recorded on the homeroom, with each teacher’s status: Primary marker carried through from the SIS. There’s no “first wins” fallback: if your SIS reports three teachers on a homeroom, Lyra stores three.

If a homeroom has the wrong teacher:

Fix the enrollments in your SIS. Add, remove, or re-flag teacher enrollments as needed; the next sync mirrors the change.
Check the primary flags. If you depend on a single primary teacher in reports or UI, make sure exactly one teacher’s enrollment has primary: true in OneRoster.

Students assigned to multiple homerooms get one (the first one Lyra encounters in the OneRoster feed). This is deterministic but not always what you want. If a student should be in homeroom B but is showing up in homeroom A, check whether they’re enrolled in both in the SIS; remove the wrong enrollment.

Sync time keeps drifting

The card: Sync schedule box defaults to a nightly run in the school’s timezone. If you set a time but the actual run is offset:

The school’s timezone. The sync runs at the chosen hour in the school’s timezone, which is the one shown under the hour. If it’s wrong, fix it in School settings; the schedule follows it.
Daylight saving transitions. Around the spring and fall transitions, the wall-clock time may shift for a few days. Self-corrects within a week.
The exact wording in History. The history lists every run with timestamp; a few minutes of drift around the scheduled time is normal (we don’t fire exactly on the minute).