Koha MARC Import Errors: Common Causes and Fixes

Koha’s staged MARC import tool is one of the most important tools in a migration. It lets you upload MARC or MARCXML files, stage them for review, and then import them into the catalogue.

When the import does not behave as expected, the problem is often in the source records rather than Koha itself. The file may contain malformed MARC, broken encoding, incomplete fixed fields, missing item data, or matching rules that do not fit the import goal.

This guide explains the most common causes of MARC import problems in Koha and how to approach them.

Error: the file will not stage

If Koha cannot stage the file, start with the basics.

Check:

• Is the file actually MARC or MARCXML?
• Is the file empty?
• Was the file compressed?
• Was the file exported in the wrong format?
• Is the file too large for your server configuration?
• Does the file contain malformed records?

A common mistake is trying to import a spreadsheet directly into Koha as if it were MARC. CSV, Excel, TSV, and JSON files must be mapped and converted before they can become MARC21 or MARCXML.

MARCReady can help with this by mapping structured files into MARC21 and exporting a Koha-ready file.

Error: records stage, but some records fail

If Koha stages the file but reports failed records, the file may contain a mix of valid and invalid records.

Common causes include:

• broken MARC structure;
• missing record terminators;
• invalid field lengths;
• incomplete Leader;
• malformed control fields;
• invalid subfield structure;
• encoding corruption.

Do not assume the whole file is safe because some records were staged successfully. A migration file can contain thousands of good records and a small number of records that need repair.

Recommended fix:

1. Identify a sample of failed records.
2. Compare them to successful records from the same file.
3. Check whether the failures come from one export source, branch, item type, or date range.
4. Repair or remove the failed records.
5. Re-stage a clean sample before attempting the full file again.

Problem: accented characters look wrong

Encoding issues are especially common with older MARC files.

Symptoms include:

• accented names displaying incorrectly;
• question marks or replacement characters;
• strange symbols in titles or notes;
• characters that look correct in one tool but wrong in Koha.

This usually happens when the file encoding is not what the import process expects. MARC files may use MARC-8 or UTF-8. If the wrong encoding is selected or the source file contains mixed encodings, characters can break during import.

Recommended fix:

• identify whether the file is MARC-8 or UTF-8;
• test a small batch with records containing accents;
• inspect titles, authors, subjects, and notes after import;
• repair encoding before importing the full catalogue.

MARCReady detects common encoding issues and applies normalisation where possible.

Problem: duplicate records are created

Duplicate records often happen when Koha cannot match incoming records to existing records.

Common causes include:

• no matching rule selected;
• matching rule based on a field that is missing from the source file;
• ISBNs formatted inconsistently;
• control numbers stored in different fields;
• records from different systems using different local identifiers.

Recommended fix:

Before importing into an existing catalogue, decide how records should match. Common matching points include ISBN, control number, title/author combinations, and local identifiers. Test the rule with a small file before applying it to a full batch.

If your ISBNs or control numbers are inconsistent, clean them before import.

Problem: records import, but items are missing

A successful bibliographic import does not always mean item data imported correctly.

If items are missing, check whether your source file includes copy-level data such as:

• barcode;
• branch;
• location;
• item type;
• call number;
• copy number;
• status.

In Koha migrations, item data is often stored in local fields such as 952. If your export file contains only bibliographic records, Koha cannot create items from data that is not present.

Recommended fix:

1. Confirm where item data is stored in the source file.
2. Confirm that the import settings are set to process item data.
3. Test with a small sample.
4. Check whether barcodes and branches appear correctly after import.

Problem: import works, but search results look poor

Sometimes the import succeeds technically, but catalogue quality is still poor.

Symptoms include:

• poor title or author search results;
• missing subjects;
• wrong material types;
• bad facets;
• missing publication dates;
• poor OPAC display.

This often points to MARC quality issues rather than import failure. The records may be structurally importable but incomplete, inconsistent, or poorly mapped.

Recommended fix:

Review fields that affect discovery, including:

• 020 ISBN;
• 100/110/111 main entries;
• 245 title;
• 260/264 publication fields;
• 300 physical description;
• 5XX notes;
• 6XX subjects;
• 7XX added entries;
• Leader and 008 fixed fields.

MARCReady can help surface these issues before import.

Best practice: test before full import

Use this process:

1. Stage a small sample.
2. Review staging warnings.
3. Import into a test Koha environment.
4. Check the records in the staff interface.
5. Check the records in the OPAC.
6. Search by title, author, ISBN, subject, and barcode.
7. Confirm items, branches, item types, and locations.
8. Adjust mapping or matching rules.
9. Repeat until the sample is acceptable.
10. Only then import the full file.

When to use MARCReady

Use MARCReady before Koha import if:

• Koha reports staging errors;
• source data is in a spreadsheet;
• vendor records contain inconsistent fields;
• imported records display incorrectly;
• you need to clean ISBNs, indicators, empty subfields, encoding, Leader, or 008;
• you want a record-by-record review before export.

Start with the free preview to review up to 3 records per upload at no cost (up to 15 per month).

Related articles

• How to Validate MARC Records Before Importing into Koha
• Koha Stage MARC Records for Import: Settings Explained
• MARC Character Encoding Problems: MARC-8, UTF-8, and Broken Accents
• Duplicate Records in Koha: Matching Rules, ISBNs, and Control Numbers