Imports

This page covers what to do when a roster or catalog import doesn’t land cleanly, whatever you uploaded. For the OneRoster ongoing sync, see OneRoster sync.

Both importers take a spreadsheet or a CSV. Only the catalog importer takes MARC, so a .mrc is a catalog file and nothing else.

Importer	Accepts
Roster import	`.xlsx`, `.xls`, `.csv`
Catalog import	`.xlsx`, `.xls`, `.csv`, `.mrc`, `.marc`

Up to 50 MB per file, as many files as you have in one import. Almost everything below is about a row or a record rather than the file that carried it, so the sections are headed by what failed rather than by format. Where the advice really is CSV-only — delimiters, quoting, encoding — it says so, and the fix is usually to upload the workbook rather than exporting it to .csv first.

Roster import: rows fail with per-row errors

Lyra processes every file in the upload: valid rows are applied (added or updated), and rows with problems are skipped or recorded as errors. The import detail page lists every affected record with its change type and reason.

What to do:

Open the import detail page. Each record kind you uploaded a file for has its own tab (button: Students, button: Faculty, button: Homerooms, button: Homeroom teachers), and each tab shows its own message: Errors count. Every record shows a change type (status: Added, status: Updated, status: Removed, or status: Error); filter a tab to button: Error to see that kind’s row-by-row failures. Errors are counted per kind, so check each tab whose message: Errors count is above zero.
Fix the rows at the source. Correct them in your SIS export — in the workbook, or in a text editor if what you uploaded was a .csv. If you don’t have the file you uploaded, select it in the card: Files strip at the top of the import detail page to download it again.
Re-upload. Lyra re-processes; previously-applied rows update again with the same values, failing rows get another chance.

Common per-row errors:

message: Missing first or last name A new student or faculty row is missing first_name or last_name. Both are required for inserts. If you mapped a whole-name column to Full name (Last, First), a value with no comma reads as a surname only; add the comma (Smith, Mary) in the file.
message: Duplicate identifier Two rows in the same file share the same identifier. Identifiers must be unique per file. Often a sign you’ve got the same patron in two grade exports.
message: Duplicate barcode or message: Duplicate email Two rows in the file (or the file plus existing patrons in Lyra) share the same barcode or email. Pick one and clear the other.
message: Invalid class year Must be a four-digit year (the year the student graduates). 9 for ninth grade is wrong; convert to the graduation year. See class year derivation. If the column holds each student’s current grade, map it to Grade (sets class year) instead of class_year when you import, and Lyra works out the class year.
message: Invalid grade A homeroom’s grade_level, or a student’s mapped grade, isn’t a grade Lyra can read. Use a number from -1 to 12 or one of the grade spellings, such as K or 3rd. A student with an unreadable grade still imports.
message: Invalid guardian emails A value in the semicolon-separated list isn’t a valid email. Semicolons (not commas) between addresses: mom@example.com, dad@example.com won’t parse; mom@example.com;dad@example.com will.
message: Invalid email Trailing whitespace, missing @, an embedded comma. Lyra strict-validates emails.
message: Invalid PIN PIN must be 4 to 12 characters with no whitespace.
message: Unknown homeroom (Students). The referenced homeroom_identifier doesn’t match any homeroom in the upload or in Lyra. The student still imports, with no homeroom. Either include the homeroom in the Homerooms file, fix the identifier, or blank the cell.
message: Missing homeroom identifier or message: Missing teacher identifier (Homeroom teachers). One side of the pair is blank. Fill the cell in.
message: Unknown homeroom, message: Unknown teacher or message: Unknown homeroom and teacher (Homeroom teachers). The cell names a homeroom or teacher that isn’t in the upload or in Lyra. Unlike a student row, a homeroom-teacher row with an unresolved reference doesn’t import at all. Either include that homeroom or teacher in the upload or fix the identifier — and when the row names both, fix both before re-running.
message: Invalid primary-teacher flag (Homeroom teachers). The value isn’t one of the accepted true/false forms (yes/true/y/1 or no/false/n/0/blank).
message: Has an active loan (Replace mode). A student or faculty patron not listed in the file has an open checkout and wasn’t removed. The patron is kept (and, if a removed homeroom would have cleared their homeroom, that clear still applies). Check the item in or transfer it, then re-run to remove the patron.
message: Students still reference homeroom or message: Homeroom teachers still reference homeroom (Replace mode). A homeroom you left out of the Homerooms file wasn’t removed because the same upload still pointed at it: a student row’s homeroom_identifier, or a Homeroom teachers row. Stop referencing it in the upload (the homeroom’s existing members in the database don’t block removal; only references in the same import do), then re-run.

The full column reference is on the Roster import formats page.

CSV: garbled names and titles

Encoding is a CSV problem and only a CSV problem. A workbook carries its text already decoded, so there is nothing to detect in a .xlsx or .xls and nothing here to go wrong; a MARC file is read as UTF-8 (see below). The rest of this section is about .csv files.

Lyra works out the encoding from the file’s own bytes — UTF-8, UTF-16, or Windows-1252, which is what Excel on Windows and Follett Destiny write. A byte-order mark is removed. So an ordinary Windows or PowerShell export imports with its accents intact, and you do not need to re-save it first.

One case is still on you, because no importer can tell it apart from correct text: text that was already garbled before you exported it. If your old system stored cafÃ¢e for café, those are the characters in the file and they import as written. Fix them at the source and re-import.

So if a title or a name still looks wrong after the import, the text was almost certainly already wrong in the file. Download the original from the card: Files strip at the top of the import detail page and open it in a text editor: what you see there is what Lyra read.

One thing encoding will not fix: Excel’s Unicode Text (*.txt) save is tab-delimited rather than comma-delimited, and Lyra’s dropzone does not take it. Save the workbook itself, or use Save As → CSV UTF-8.

The Excel double-click problem

When you double-click a CSV in Excel, Excel applies aggressive auto-formatting:

Long numeric strings (9780123456789) become scientific notation (9.78012E+12) and lose precision on save.
Dates are reformatted to a regional default and may lose century digits (1965 becomes 65).
Leading zeros are stripped from identifier strings (007 becomes 7).

The safe path: open CSVs through Data → From Text/CSV in Excel, which lets you set each column’s type explicitly. Or edit CSVs in a text editor, not a spreadsheet.

Better still, don’t convert it at all: upload the workbook. Lyra reads .xlsx and the older .xls directly, and a workbook carries each cell’s own value and type, so there is no conversion left for Excel to get wrong — no encoding to pick, no trailing blank line, and a 13-digit ISBN stays a 13-digit ISBN.

Records that were skipped

A record Lyra can’t read is skipped and the rest of the file keeps going, whatever the format. Skipped records are collected on the import’s tab: Skipped tab (see Catalog import), each listed under button: From by the row or record it sat on in the file, and beside that the reason it couldn’t be read. When the upload carried more than one file, a button: File column says which one each record came from.

Each reason names what Lyra found and what to change. Find yours below.

“This row has 2 values but the header row names 3 columns”

A row whose values don’t line up with the header row. The two counts are what that row had and what the header named, and the button: From column says which row to open.

Fewer values than the header names. The row is truncated, or it’s a blank-looking line at the end of the file. Destiny’s exporter ends every file it writes with a whitespace-only line, which reads as one value where the header named several — that one is harmless, and the records above it all imported. The other common cause is an unescaped comma inside a value that split one field into two, leaving a later field empty.
More values than the header names. In a .csv, almost always an unescaped comma inside a value: Smith, John,BK-1,Fiction is four values, not three. Wrap it in quotes ("Smith, John",BK-1,Fiction) or, better, upload the workbook instead of exporting it to .csv — a .xlsx has no delimiter to escape. In a spreadsheet it’s a value sitting past the last column the header row named: a stray note typed to the right of the table, or a merged title row above the header that pushed one row’s cells out of line. Clear the cell, or give the column a heading.

Lyra skips these rather than shifting the remaining values left to fit, because a row imported with its author in the call-number column is wrong in a way nobody notices.

“A quotation mark opens in this row and is never closed”

A " in a .csv value with no partner anywhere after it. One stray quote can swallow the rest of the file, which is why the reason names the row it started on rather than the row Lyra gave up on.

Measurements are the usual cause: 12" globe opens a quote that never closes. Escape it by doubling ("12"" globe"), or upload the workbook.

“This row has a quotation mark in the middle of a value”

A " inside a .csv value that didn’t start with one, so the file never said where the value ends. Same cause and same two fixes as above.

“This row is too long to read”

Lyra stopped reading the row before it ended. In practice this is the tail of an unclosed quote earlier in the file: everything after that quote became one enormous value. Fix the quote it started on and this row reads normally.

A MARC record that won’t parse

The reason reads “This record isn’t valid MARC, so nothing could be read from it.” Nothing in the record survived, so there is nothing for Lyra to name beyond that — download the skipped records below to see the bytes it choked on.

Common causes:

Wrong format. Lyra accepts ISO 2709 MARC binary. MARCXML, MARC21 text dumps, and “MARC-shaped” exports from a vendor’s own format may not parse. If you exported from Destiny, OPALS, or another ILS, confirm the export was “MARC binary” or “MARC 21 binary,” not a text or XML variant.
Non-UTF-8 encoding inside the MARC record. Lyra reads MARC records as UTF-8 only. Older exports in MARC-8 (or other legacy encodings) produce mojibake or fail to parse. Re-export from your source system in UTF-8 if possible.
Truncated record. If the export was interrupted (network drop mid-download, a too-small file size), the last record is partial and bails. Re-export.

Getting the skipped records back

Use button: Download ▸ menu item: Skipped records to pull just those records back out — a skipped-records.mrc when they all came from one MARC file, or a skipped-records.zip with one file per source file when they span several — repair them in your cataloging tool or spreadsheet, and re-import them. No need to re-run the whole file.

If the problem turns out to be the whole file rather than a handful of records — the wrong format or the wrong encoding — select the file in the card: Files strip at the top of the import detail page to download the original upload and re-export from there.

“ISBN looks valid but no cover loaded”

Not strictly an import failure, but commonly mistaken for one. See Covers and images for the cover-loading flow. Short version: cover lookup runs inline with the catalog import, for every record that carries an ISBN and no cover of its own — a MARC record and a Books by ISBN spreadsheet row go the same way. So if no cover appears after the import finished, the ISBN isn’t in the lookup dataset.

A Books by title row has no ISBN to look one up by, so it imports with no cover by design. Adding an isbn column, or importing those titles from MARC instead, is what fills it.

Roster import: identifier mismatch on re-import

When you re-import a roster file against an existing patron list, Lyra matches by the patron’s identifier. If a patron’s identifier changed between the prior import and this one, Lyra treats them as a new patron and creates a duplicate.

The fix is don’t change identifiers between imports. Pick a stable identifier (the SIS’s student ID, typically) on the first import and keep using it. If the SIS regenerated identifiers (rare, but happens after a SIS migration), the right path is a manual re-keying via a one-time staff-side operation, not a re-import.

If you’ve already created duplicates by importing under a new identifier, contact support for cleanup; the merge is not self-service.

Catalog import: the same patterns

The same encoding and Excel double-click problems affect a catalog import given a .csv, and both go away if you upload the workbook instead. A MARC file sidesteps all of this — no delimiter to escape, no quoting, and no spreadsheet to open it in — so where your old system can export MARC, that is the export to ask it for. The catalog importer comes in three templates (non-book items, books by ISBN, and books by title), each with its own columns; see Catalog import formats for the per-template reference. The columns differ from the roster files, but the encoding and spreadsheet failure modes are the same.

One item-specific gotcha: in the books template, a row whose isbn can’t be looked up imports with an empty title and lands on the tab: Issues tab. Which flag it carries tells you what to fix. A cell Lyra couldn’t read as an ISBN at all is flagged status: Unreadable ISBN and the row shows you the cell; a blank cell, or a well-formed ISBN with no record behind it, is flagged status: Missing title. If a batch of book rows comes back as issues, suspect ISBNs mangled into scientific notation by Excel (see the double-click problem above), or a file exported from another system that writes several ISBNs into one cell — the isbn column takes one per row.

When to email support

Wherever an import can go wrong, Lyra offers the same three ways on: button: Ask Vega about this file, the page of this guide that covers what you’re looking at, and button: Email support, which opens a message already carrying the import’s id and the page you were on. button: Ask Vega about this file is offered in a library only — Vega answers about one library’s catalog, and the roster lives on the school — and not at all in an account whose owner has turned Vega off.

Where they appear depends on what failed. A whole import or sync run that stopped carries them in a panel headed message: Not sure what went wrong? on the run’s own page. A single row with something wrong carries them on the row: point at (or tap) what the button: Issues column says in a roster run’s changes list, or a reason on the tab: Skipped tab, and the same three appear beside it.

If the error report is unclear, the validation passes but the import is producing unexpected records, or the import is partial without a clear reason, email support@lyralibrary.com with:

The file you uploaded (or a representative sample).
The error report Lyra produced.
What you expected to happen.

We can almost always tell you within an hour which column or row is the problem.