Roster import formats

This is the specification for the files the roster importer reads. For the workflow that consumes them — where the importer lives, choosing Replace or Update, dry runs, and reading results — see Roster import.

Accepted files

Three file types, up to 50 MB per file:

Extension	Format
.csv	One of the five templates below
.xlsx	One of the five templates below, as an Excel worksheet
.xls	The same, in the older Excel format many SISes still emit

One import carries any number of files, in any combination. Several files of one template is a normal case — students exported per grade import as one set of students. A workbook counts as one file per sheet: each sheet is read on its own, so a single book holding a students sheet, a faculty sheet and a homerooms sheet imports all three. Lyra tells the two Excel formats apart from the file itself, so a report saved straight out of your SIS works without a conversion step.

Exporting from a student information system?

Upload the workbook your SIS gave you, rather than saving each sheet as CSV first. A spreadsheet carries no encoding to guess at and no ragged last line, which are the two ways an Excel-exported CSV gets mangled, and Lyra reads a numeric identifier as the digits it shows rather than as 1.2345E+04.

Lyra also recognizes the column names two published roster specifications use — 1EdTech OneRoster v1.1 CSV (users.csv, classes.csv, enrollments.csv) and Clever’s SFTP spec (students.csv, teachers.csv, sections.csv, staff.csv) — so for an export in either vocabulary, Lyra fills in the column mapping and you confirm it rather than rewrite the file. See Column names Lyra recognizes.

Two systems are deliberately absent. PowerSchool Quick Export writes whatever fields you ticked, so there is no fixed set of headings to match; Follett Destiny takes patrons as XML through its Patron Import Converter rather than as CSV. A spreadsheet from either still imports: you pick what each of its columns holds in the import dialog’s column mapping step.

An import is school-scoped. It populates the patron and homeroom records shared by every library in the school.

The five templates

roster-templates.xlsxEvery roster template, one sheet each. Fill in what you need — a blank sheet is ignored.

Or one template at a time, as a CSV:

• Students
• Faculty
• Homerooms
• Homeroom teachers
• Community

A roster import comes in five templates rather than one catch-all format. All five are independently optional, and one upload can carry any combination of them, including several files of the same template.

Template	One row per
Students	Student
Faculty	Teacher or staff patron
Homerooms	Homeroom
Homeroom teachers	(homeroom, teacher) pair
Community	Community patron

The workbook is the shape a filled-in SIS export usually has, and the shape you can upload in one piece. Each sheet holds its header row and nothing else.

Fill in the sheets you need and leave the rest alone. A sheet with nothing under its header row is ignored, which matters most in a Replace import: an untouched tab is not an empty file, so leaving Faculty blank leaves your faculty alone rather than removing all of them. Working in a workbook also sidesteps the two ways an Excel-exported CSV gets mangled — there is no encoding to guess at, and an identifier stays the digits it shows rather than turning into 1.2345E+04.

You do not pick the template — Lyra reads it off the file. Drop your files in and each one’s column headings decide which template it is: each template’s vocabulary resolves the headings its own way, and whichever recognizes the most columns is the one the file is written in. An honorific column makes a file Faculty; a class_year, pin or guardian_emails column makes it Students; an affiliation column makes it Community. The dialog names what it decided on each file’s row, with a control to correct it before anything is imported. Every template is offered there; picking one the file’s columns don’t fit sends the file to the column mapping step, which says what that template still needs.

One case cannot be decided from columns alone. A file of identifier, first name, last name and email is a valid Students, Faculty and Community file, spelled identically. The name breaks the tie — it is worth one column, so teachers.xlsx reads as Faculty and volunteers.xlsx as Community — and failing that the file reads as Students, the largest of the three in every school. For a sheet of a multi-sheet workbook the sheet’s name is what counts, not the workbook’s, so naming your tabs Students, Faculty and Community is worth doing.

What a file must carry

Before a template can be read off a file at all, the file has to say something only that kind of record has. An identifier column alone never settles it: it is the join key on every template.

Template	Needs
Students	Any one of first_name, last_name, email or barcode
Faculty	Any one of first_name, last_name, email or barcode
Homerooms	An identifier column, and a name or grade_level column
Homeroom teachers	A homeroom_identifier column and a teacher_identifier one
Community	Any one of first_name, last_name, email, barcode or affiliation

One of these is the whole bar for a patron file — not a name and a way to reach them. Students, Faculty and Community ask for the same columns because this check only decides whether a file lists people at all; which of the three it lists is the separate question above, settled by the columns further down each template and then by the file’s name.

A file matching no template isn’t refused. It goes to the column mapping step, where you say which of its columns hold these, and the step won’t let the import go ahead until the template’s needs are met. It names what’s missing, for example message: Homerooms needs an Identifier column, and a Name or Grade column..

Column names Lyra recognizes

Your headings do not have to match the template’s spelling. Case, punctuation and underscores are ignored (first_name, First Name and FIRST_NAME are one column), and each of the column tables below carries a Recognized headings column listing the other labels read as that Lyra column.

Those labels come from two published roster specifications and nowhere else: 1EdTech OneRoster v1.1 CSV (users.csv, classes.csv, enrollments.csv) and Clever’s SFTP spec (students.csv, teachers.csv, sections.csv, staff.csv).

A file imports as it is only when every heading is one of Lyra’s own column names for the template it’s read as, and it has what that template needs (below). A filled-in starter template qualifies, and so does a Lyra export. Any other file, including a OneRoster or Clever export whose every heading is listed here, goes through the column mapping step, where you confirm what each column holds before it imports. The recognized headings are where Lyra’s suggestions there start. After them it guesses from what an SIS export usually calls a column: a heading sharing words with a Lyra column’s name (E-mail, Student Email), Home_Room or HR for a student’s homeroom, Section # or Class ID for a homeroom’s identifier, Employee ID for a teacher’s, and Grd, Gr or Grade for a grade. Those are only suggestions: you see each one, and any heading not listed here can still be mapped by hand.

A heading can mean different things in different files, which is why they are listed per template rather than once. Clever writes Teacher_id for a teacher’s own id in teachers.csv and for the teacher a section points at in sections.csv, and Section_id the same way. Lyra resolves headings against the template the file is being read as, so both are read correctly — another reason to glance at what Lyra decided each file is before importing.

In the mapping step each Lyra column goes to one of your columns. In a file that skips the step because it uses Lyra’s own names, a column name that appears twice is read from the leftmost.

Guardian contacts are not matched

Clever’s Contact_email is not read as guardian_emails. Clever gives a student several guardians by repeating the student’s row once per contact, where Lyra takes one row with a semicolon-joined list — so importing it as-is would reject every repeated row as a duplicate identifier. Flatten guardian emails into one row per student first; see Flattening parent emails.

Columns Lyra has no place for — Gender, Race, DOB, Middle_name, Username, Status, enabledUser, the Contact_* fields, and state, school and org ids — are recognized and ignored rather than treated as unrecognized, so leaving them in an export costs nothing: in the mapping step they start as setting: Don't import. A file made of nothing but these can’t be imported as a pile of blank rows, because the mapping step won’t go ahead until the file has a column the template needs.

Students columns

Column	Recognized headings	Accepted values	Blank behavior	On update
identifier Optional	sourcedId, Student_id, Student_number	Non-empty string, stable across re-imports	Lyra assigns one. Provide your own when you want re-imports to match the same patrons.	Join key. Never updated; identity itself.
first_name Required on new patrons	givenName	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
last_name Required on new patrons	familyName	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
preferred_name Optional	Preferred_first_name	Any string	Patron is referred to by first_name in the UI.	Overwrites; blank clears the previously-set preferred name.
email Recommended	Student_email	Valid email address; lowercased on parse	Patron cannot sign in to the OPAC, and overdue notices have no recipient.	Overwrites; blank clears the email.
barcode Optional	—	Non-empty string, at most 50 characters	Unique barcode assigned on insert. Updates leave the existing barcode in place.	Overwrites; provide a new value to change it. A barcode can’t be cleared.
pin Optional	password	4 to 12 characters, no whitespace	Random 4-digit PIN assigned on insert. Updates leave the existing PIN in place.	Overwrites; provide a new value to rotate.
class_year Optional	Graduation_year	Four-digit graduation year from 1000 to 9999, e.g. 2031	Student’s grade cannot be inferred.	Overwrites. Grade is recomputed from class_year plus the school calendar on read.
guardian_emails Optional	—	Semicolon-joined list of valid emails, e.g. mom@x.com;dad@x.com	No guardian notice copies are sent.	Overwrites the full list; blank clears all guardian emails.
homeroom_identifier Optional	—	An identifier from the Homerooms file, or of an existing homeroom	Student belongs to no homeroom. Common and valid for high schoolers.	Sets homeroom membership. A blank value clears the homeroom; omitting the column entirely leaves the existing homeroom untouched.

The homeroom_identifier column has three modes

• Column present, with a value — sets (or moves) the student to that homeroom.
• Column present, value blank — clears the student’s homeroom.
• Column omitted entirely — leaves the existing homeroom untouched. It changes only if a removed homeroom cascades and clears it.

Faculty columns

Column	Recognized headings	Accepted values	Blank behavior	On update
identifier Optional	sourcedId, Teacher_id, Teacher_number, Staff_id	Non-empty string, stable across re-imports	Lyra assigns one. Provide your own when you want re-imports to match the same patrons.	Join key. Never updated; identity itself.
first_name Required on new patrons	givenName	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
last_name Required on new patrons	familyName	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
preferred_name Optional	—	Any string	Patron is referred to by first_name in the UI.	Overwrites; blank clears the previously-set preferred name.
email Recommended	Teacher_email, Staff_email	Valid email address; lowercased on parse	Patron cannot sign in to the OPAC.	Overwrites; blank clears the email.
barcode Optional	—	Non-empty string, at most 50 characters	Unique barcode assigned on insert. Updates leave the existing barcode in place.	Overwrites; provide a new value to change it. Can’t be cleared.
honorific Optional	Title	Mr., Ms., Mrs., Dr., etc.	Faculty patron has no honorific shown in the UI.	Overwrites; blank clears.

The Faculty template has no pin, class_year, guardian_emails, or homeroom_identifier column. A teacher’s link to a homeroom is carried by the Homeroom teachers template, not by the faculty row.

Community columns

One row per community patron: someone who borrows without being on your roster, such as a parent volunteer, a substitute or a visiting reader. No SIS exports these, so the template has no other vendor’s headings.

Column	Accepted values	Blank behavior	On update
identifier Optional	Non-empty string, stable across re-imports	Lyra assigns one. Provide your own when you want re-imports to match the same patrons.	Join key. Never updated; identity itself.
first_name Required on new patrons	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
last_name Required on new patrons	Any string	New row rejected if blank. Updates may omit to keep the existing value.	Overwrites existing value.
preferred_name Optional	Any string	Patron is referred to by first_name in the UI.	Overwrites; blank clears the previously-set preferred name.
email Recommended	Valid email address; lowercased on parse	Patron cannot sign in to the OPAC.	Overwrites; blank clears the email.
barcode Optional	Non-empty string, at most 50 characters	Unique barcode assigned on insert. Updates leave the existing barcode in place.	Overwrites; provide a new value to change it. Can’t be cleared.
affiliation Optional	Free text: Parent volunteer, St. Anne's parish, Substitute	No affiliation shown.	Overwrites; blank clears.

The Community template has no pin, class_year, guardian_emails or homeroom_identifier column: a community patron signs in to the OPAC with an emailed code, and belongs to no homeroom. Nor can one be named as a teacher in the Homeroom teachers template.

An identifier held by a student or faculty member is refused, as message: Identifier belongs to a student or faculty member, and so is one that a Students or Faculty file in the same upload adds. Moving someone off the roster into the community is a merge, not an import.

In a school connected to a roster source, the Community template is the one that still adds patrons and changes every column — nothing about a community patron is the source’s.

Columns the mapping step adds

Two Lyra columns exist only in the column mapping step, for the shapes an SIS export usually takes. Neither is a column on a template, so a file can only use them by mapping one of its own columns there.

• Full name (Last, First), on Students, Faculty and Community. For a column that holds a whole name written Smith, Mary Ann. Lyra splits it at the first comma: what’s before it is last_name, what’s after is first_name, so a surname of several words survives. A value with no comma is read as all surname and no first name, so a new patron’s row is rejected as message: Missing first or last name and an existing patron keeps the first name they have. Mapping this column clears First name and Last name from any other column, and the other way round. Only the comma form is offered, because First Last can’t be split without guessing where a first name like Mary Ann ends.
• Grade (sets class year), on Students. For a column that holds each student’s grade this year. The import turns it into the class_year Lyra stores, the same way as the class year derivation, using your school’s academic year start and highest grade and today’s date in the school’s time zone. It accepts the grade spellings below. A grade Lyra can’t read is reported as message: Invalid grade and the student still imports, with their class year left as it was (none, for a new student). A blank value clears the class year, as a blank class_year does. It can’t be mapped alongside Class year: picking one clears the other.

Homerooms columns

Column	Recognized headings	Accepted values	Blank behavior	On update
identifier Required	sourcedId, Section_id	Non-empty string, stable across re-imports	Row rejected if blank.	Join key. Never updated.
name Required on new rows	title	Any string (e.g. Mrs. Boza's Homeroom, Grade 3, Room 12)	New row rejected if blank. Updates may omit.	Overwrites existing name.
grade_level Optional	grades, Grade	A grade from -1 (Pre-K) through 12, written as a number or any of the grade spellings	Homeroom has no associated grade.	Overwrites; blank clears.

Two rules are specific to this template:

• identifier is required. Unlike students and faculty, Lyra does not assign one. The identifier is what student rows and homeroom-teacher rows reference, so it has to be a value you control.
• name is unique within the school, compared case-insensitively. A row whose name collides with another row in the same file, or with an existing homeroom carrying a different identifier, is rejected as message: Duplicate homeroom name.

Homeroom teachers columns

Column	Recognized headings	Accepted values	Blank behavior	On update
homeroom_identifier Required	classSourcedId, Section_id	An identifier from the Homerooms file, or of an existing homeroom	Row rejected if blank or unresolved.	Half of the join key.
teacher_identifier Required	userSourcedId, Teacher_id	An identifier from the Faculty file, or of an existing faculty patron	Row rejected if blank or unresolved.	Half of the join key.
is_primary Optional	primary	yes / true / y / 1 for true; no / false / n / 0 / blank for false	Treated as false.	Overwrites the primary flag.

Recognized is_primary values are matched case-insensitively after trimming. Any other non-blank value is an message: Invalid primary-teacher flag issue and the flag is left unchanged.

A homeroom can have any number of teachers attached, with at most one marked primary. Provide one row per (homeroom, teacher) pair you want to exist.

Value formats

• Headers. A header row is required, and it is the first row of the file or sheet. Columns may be in any order, header names are matched by the rules above or by the mapping you confirmed, and columns mapped to setting: Don't import are ignored. Whitespace around every value is trimmed.
• Omitted columns. A column left out of the file entirely is not written. This is distinct from a column present with a blank value, which usually clears the field — see each column’s blank behavior above. It is the difference between “leave this alone” and “clear it”, and it is why an unrecognized heading is dropped rather than carried through as an empty string.
• Encoding. For a CSV, detected from the file: UTF-8, UTF-16, or Windows-1252 — the last being what Excel on Windows writes — so accented names survive whichever your SIS produced. A byte-order mark is removed. A spreadsheet carries no encoding to detect.
• Spreadsheets. .xlsx and .xls are read the same way. Every sheet in a workbook is read, each on its own: its first row is its header, matched by the same rules as a CSV’s, and the template is worked out from that sheet’s own columns. A sheet with nothing below its header row is ignored, so a workbook’s blank tab costs nothing. In the import dialog each sheet gets its own row under the file, labelled with the tab’s own name, so naming your tabs is worth doing twice over. Afterward, the import’s page lists the workbook once — as the single file you uploaded, which is what a download hands back. Cells keep the type Excel gave them: an identifier or barcode stored as a number comes across as the digits it shows, and a date cell as the day it shows rather than as a serial number.
• Unreadable rows. A CSV row with the wrong number of fields, or a spreadsheet row with values in columns the header row never named, is dropped and the rest of the file still imports. Rows are never shifted to fit, so a name with an unescaped comma is dropped rather than silently importing into the wrong columns. Many exporters end every file with a blank or whitespace-only line, and that line goes the same way. Unlike the catalog importer, a roster import does not list the rows it dropped — if a file’s counts come back lower than you expected, that is where to look.
• Refused files. A file is refused before the import runs, on the row it sits on in the dialog, when it is larger than 50 MB (message: This file is too large.), empty (message: There is nothing in it.), has no readable header row (message: There is no header row.), is a workbook whose every sheet has column names and nothing below them, such as an unfilled template (message: There are no records in it.), or will not open as the kind of file its extension claims (message: This file could not be read.). A file whose columns don’t match a template isn’t refused: it goes to the column mapping step instead. Refusing one file or one sheet doesn’t cost you the rest of the upload.

An example

A minimal four-file roster: two teachers, two homerooms, three students, and the teacher-to-homeroom assignments.

homerooms.csv:

identifier,name,grade_level
hr-3-smith,Grade 3 — Smith,3
hr-3-garcia,Grade 3 — Garcia,3

faculty.csv:

identifier,barcode,email,first_name,last_name,preferred_name,honorific
F100,F100,jane.smith@school.org,Jane,Smith,,Mrs.
F101,F101,robert.garcia@school.org,Robert,Garcia,Bob,Mr.

students.csv:

identifier,barcode,pin,email,first_name,last_name,preferred_name,class_year,guardian_emails,homeroom_identifier
S2031A,S2031A,,mia.patel@school.org,Mia,Patel,,2031,parent1@example.com;parent2@example.com,hr-3-smith
S2031B,S2031B,1234,liam.oconnor@school.org,Liam,O'Connor,,2031,liam.parent@example.com,hr-3-smith
S2027C,S2027C,,ava.johnson@school.org,Ava,Johnson,Avery,2027,,hr-3-garcia

homeroom_teachers.csv:

homeroom_identifier,teacher_identifier,is_primary
hr-3-smith,F100,true
hr-3-garcia,F101,true

On import this creates two homerooms, two faculty patrons, and three students; assigns Mia Patel and Liam O’Connor to hr-3-smith and Ava Johnson to hr-3-garcia; sets Mia Patel’s notice emails to both parents, Liam O’Connor’s to one (with a PIN of 1234 for sign-in), and leaves Ava Johnson’s empty; and stores Jane Smith and Robert Garcia as the primary teachers of their homerooms.

The same sheets in one workbook import identically. Re-uploading either unchanged is a no-op on every row: every join key matches, every value matches, nothing is updated.

Matching rows to records

identifier is the join key on Students, Faculty, Community and Homerooms:

• Identifier exists in Lyra — the row is an update. Non-identifier columns overwrite existing values; blanks clear, where the column allows.
• Identifier doesn’t exist — the row is an insert. A new record is created.

The Homeroom teachers template joins on the (homeroom_identifier, teacher_identifier) pair rather than a single column; behavior is otherwise the same.

Identifiers must stay consistent across re-imports. If a first import used Student ID and a second uses User ID, every row in the second import is a no-match insert and the roster ends up with duplicate patron records.

Cross-file references

Three columns point across templates, all by identifier:

On	Column	Points at
Students	homeroom_identifier	identifier on Homerooms
Homeroom teachers	homeroom_identifier	identifier on Homerooms
Homeroom teachers	teacher_identifier	identifier on Faculty

A reference resolves against either a row in the same upload or a record that already exists in Lyra. A students-only upload can assign students to homerooms created by a previous import; a homerooms-only upload can be followed later by a homeroom-teachers file without re-uploading the homerooms.

Unresolved references behave differently by template:

• On a Students row, the patron is still added or updated and the homeroom link is dropped, reported as an message: Unknown homeroom issue.
• On a Homeroom teachers row, the row does not apply at all, reported as message: Unknown homeroom, message: Unknown teacher, or message: Unknown homeroom and teacher when neither end resolves. These are distinct from message: Missing homeroom identifier and message: Missing teacher identifier, which mean the cell was left blank.

Class year derivation

class_year is stored as the four-digit graduation year. Lyra computes a student’s current grade from that plus the school calendar’s academic year start and the school’s highest grade. Storing the graduation year rather than the current grade means rollover happens on its own: a 3rd grader in the 2025/26 academic year is a 4th grader in 2026/27, with no roster edit.

When a SIS export carries graduation year, use it directly. When it doesn’t — common in K–8 schools — derive it:

class_year = current_school_year_end + (highest_grade − current_grade)

For a K–8 school whose year ends in 2026, with a student currently in grade 3:

class_year = 2026 + (8 − 3) = 2031

For pre-K rows, apply the same formula treating pre-K as grade −1.

If your export has each student’s current grade, you don’t need the formula. Map that column to Grade (sets class year) in the column mapping step and the import works out the class year the same way, from the school’s academic year start and highest grade and today’s date in the school’s time zone.

Grade spellings

A homeroom’s grade_level, and a student’s grade mapped to Grade (sets class year), accept a grade written the way SIS exports write it. Case, spaces and punctuation don’t matter, and a Grade or Gr before or after the value is ignored (Grade 3, 3rd Grade, Gr. 03).

Grade	Accepted spellings
Pre-K	-1, PK, Pre-K, PreK, Pre-Kindergarten, TK, Transitional Kindergarten
Kindergarten	0, 00, K, KG, Kinder, Kindergarten
1 through 12	The number, with or without a leading zero or an ordinal ending: 3, 03, 3rd, Grade 3

Transitional kindergarten reads as pre-K, the grade before kindergarten in Lyra’s scale. Any other negative number, a grade above 12, or text that names no grade is reported as message: Invalid grade.

Guardian emails

guardian_emails exists on the Students template only. It is what lets overdue notices, ready-hold notices, and due-soon notices reach parents and guardians in addition to the patron.

The value is a single string of one or more valid email addresses joined by semicolons:

mom@example.com;dad@example.com

• Semicolons, not commas. A comma-separated value parses as one malformed address.
• Surrounding whitespace is trimmed. a@x.com;b@x.com and a@x.com; b@x.com both parse.
• Addresses are lowercased and empty entries are dropped on parse.
• The patron’s own address is not duplicated here. email is its own column; guardian_emails is for additional recipients.
• Blank clears. An empty cell on update removes all guardian emails for that patron.

Import outcomes

Every row that parsed lands on a record, and every record the import touched is listed under one change type. There is no rolled-up number and no per-file bucket.

Change	Meaning
status: Added	A new record was created.
status: Updated	An existing record changed. Expands to a field-level before/after diff.
status: Unchanged	The row matched what Lyra already holds, so nothing was written. Counted toward none of a tab’s totals.
status: Removed	A record was deleted. Replace mode only.
status: Error	A row didn’t import cleanly, or a removal was blocked. Codes below.

A row that applied can still carry an issue, and a row that carries an issue still applied — the three groups below are not severities of one thing.

status: Unchanged is the code message: Nothing to update, and it is not an error: the row named a record whose every value already matches the file. Re-uploading an export you changed one cell in is mostly this, which is what lets the rows that did move stand out. A row carrying an issue stays status: Updated even when it changes nothing, because the issue is the thing you need to see — except in a school connected to a roster source, where a row whose only changes were to columns the source owns is the error message: Only changes what your roster source owns.

Per-row issues (row still applies)

The row is inserted or updated, but one value was rejected and was cleared or skipped.

Issue	Template(s)	What it means
message: Invalid PIN	Students	pin is shorter than 4 characters, longer than 12, or contains whitespace. The stored PIN is left as it is, not cleared.
message: Invalid email	Students, Faculty, Community	email is not a valid email address.
message: Invalid guardian emails	Students	A value in the semicolon-separated list isn’t a valid email. The whole list is skipped, not just the bad one.
message: Invalid class year	Students	class_year is not a four-digit year from 1000 to 9999.
message: Unknown homeroom	Students	The referenced homeroom doesn’t exist in the upload or in Lyra. The student’s homeroom is cleared.
message: Invalid grade	Homerooms, Students	A homeroom’s grade_level, or a student’s mapped Grade (sets class year) column, is not a grade Lyra can read; see grade spellings. A student still imports, with their class year left as it was (none, for a new student).
message: Invalid primary-teacher flag	Homeroom teachers	is_primary is not one of the recognized true/false values.
message: Skipped the columns your roster source owns	Students, Faculty	In a school connected to a roster source, the row also changed a column the source owns. Everything but barcode, pin and guardian_emails is skipped; see In a school connected to a roster source.

Row-skipping errors (no insert or update)

The row is not applied. Fix it in the source file and import again.

Error	Template(s)	What it means
message: Invalid identifier	Homerooms	identifier is empty. On Students, Faculty and Community a blank one is assigned instead.
message: Duplicate identifier	Students, Faculty, Community, Homerooms	Two rows in the same file share the same identifier.
message: Identifier belongs to a community patron	Students, Faculty	The identifier is already held by a community patron, whom no roster file describes. Merge the two records rather than re-importing.
message: Identifier belongs to a student or faculty member	Community	The identifier is already held by a student or faculty member, or a Students or Faculty file in the same upload adds it. Merge the two records if they are one person.
message: Missing first or last name	Students, Faculty, Community	first_name or last_name is empty on a new patron.
message: Duplicate barcode	Students, Faculty, Community	Two rows in the file — or a row and an existing patron — share the same barcode.
message: Duplicate email	Students, Faculty, Community	Two rows in the file — or a row and an existing patron — share the same email.
message: Missing homeroom name	Homerooms	name is empty on a new homeroom.
message: Duplicate homeroom name	Homerooms	name collides with another row, or with an existing homeroom under a different identifier.
message: Missing homeroom identifier	Homeroom teachers	homeroom_identifier is empty.
message: Missing teacher identifier	Homeroom teachers	teacher_identifier is empty.
message: Unknown homeroom	Homeroom teachers	The referenced homeroom doesn’t exist in the upload or in Lyra.
message: Unknown teacher	Homeroom teachers	The referenced teacher doesn’t exist in the upload or in Lyra.
message: Unknown homeroom and teacher	Homeroom teachers	Neither end of the pair resolves. Both are named at once so one import surfaces both fixes.
message: Duplicate teacher assignment	Homeroom teachers	The same (homeroom, teacher) pair appears twice in the file.
message: Not listed by your roster source	Students, Faculty	In a school connected to a roster source, the identifier matches no one the source lists as that kind. The source decides who is on the roster, so the importer adds no one.
message: Only changes what your roster source owns	Students, Faculty	In a school connected to a roster source, every change the row made was to a column the source owns, so nothing was left to apply.
message: Homerooms come from your roster source	Homerooms, Homeroom teachers	In a school connected to a roster source, homerooms and their teachers are the source’s, so no row of either file applies.

Replace-mode delete failures (the existing record is kept)

In Replace mode, records absent from a file are removed unless a constraint prevents it. The record stays and the failure is reported as an error.

Error	Template(s)	What it means
message: Has an active loan	Students, Faculty, Community	Patron has an open checkout and can’t be removed. The patron is kept; if a removed homeroom would have cleared their homeroom, that clear still applies.
message: Students still reference homeroom	Homerooms	A Students row in this same upload points its homeroom_identifier at the homeroom being removed.
message: Homeroom teachers still reference homeroom	Homerooms	This same upload’s Homeroom teachers file references the homeroom being removed.

Only a reference from the same upload blocks a homeroom removal. Students and teachers attached to the homeroom in the database do not — see Homeroom removal in a Replace import.

See also

• Roster import — the importer itself: preparing files, Replace vs. Update, dry runs, and results.
• OneRoster roster sync — the automatic alternative for a OneRoster-capable SIS.
• Catalog import formats — the same reference for the other importer.
• Imports troubleshooting — encoding and spreadsheet failures.