Import Troubleshooting

When an import doesn’t go as expected, TrackEd has built-in tools to help you work out what went wrong. Error messages appear directly on the Import page with colour-coded indicators, and most problems can be fixed by checking a few common things before contacting support.

This article covers the most common import errors, how to read validation messages, what to do when OneSchool or QCAA changes a file format, where to find diagnostic tools like the Import Helper and Import Log, and how to clean up incorrect data using the Utilities page. For a general overview of how imports work, see Getting Data into TrackEd.

In this article

---

Quick Start Guide

A quick reference for what to do when an import fails. For a full explanation of the diagnostic tools and settings, see the Training Video and Deep Dive below.

1. Go to the Import page in TrackEd.
2. Look at the import queue for any coloured “More Info” buttons next to failed imports.
3. An orange button is a warning. Click it to read the warning text.
4. A pink button is a header validation error or an error code. Click it to view the details.
5. For a validation error, click the “What went wrong” option to see the suggested fixes.
6. Check that the correct file was downloaded from the source system (for example OneSchool) and that it was freshly exported.
7. Confirm the correct import type was selected in TrackEd.
8. Close TrackEd, reopen it, and try the import again with a fresh file.
9. If the error persists, check you are running the latest version of TrackEd by comparing your version to the current release on the TrackEd Downloads page.
10. For error codes or other issues, click the blue “Import Helper” button in the bottom-right corner of the Import page.
11. Save the generated report and email it to support@trackedapp.com.au.
12. De-identify any files before sending them to support.

---

Training Video

• 0:01 Simulating a Failed Import: What a header validation error looks like when the wrong file is dropped onto an import.
• 0:34 Common Causes of Validation Failures: Why opening a Student Summary in Excel causes errors, and why some QCAA files need to be opened first.
• 1:01 When a Source System Changes Its File Format: Spotting a small difference between the expected and imported header, and what to send support.
• 1:38 Reading the Error Details Page: Using the expected-versus-imported header comparison and the row-count indicator.
• 1:55 Using the Import Helper: Generating a detailed diagnostic report for error codes with the blue Import Helper button.
• 2:14 Reviewing the Import Log: Finding the Import Log in Settings, exporting it as an Excel file, and sending it to support.
• 3:22 Resetting a Stuck Import Queue: What to do when an import sits on purple for hours with no progress.

---

Deep Dive

A closer look at import-related settings, what each option does, and the full range of cleanup utilities available when data needs to be corrected.

• 0:02 Import Settings Overview: Where the import settings sit on the Settings page and the recommended defaults.
• 0:43 Server Processing and Timeout Troubleshooting: How “Send imports to server when possible” works and when to turn it off temporarily.
• 1:27 Student Data Import Options: DSL import management, absence and behaviour total updates, and reducing Student Summary dependency.
• 3:18 Preferred Names Configuration: The two approaches to handling preferred versus legal names during imports.
• 4:15 Ignore Lists and Roll Class Omissions: Timetable, GPA, QCE, and roll class ignore lists for filtering imported data.
• 5:40 Attendance Settings and Rollover Month: Attendance calculation settings and the absence and behaviour rollover month for the start of the year.
• 6:58 Reset Import Queue and Revise Headers: Clearing stuck imports and updating expected headers for spelling changes only.
• 7:59 Data Cleanup Utilities: Results, attendance, tags, photos, and senior schooling cleanup options.

---

Detailed Guide

Reading Error Messages

When an import fails, a coloured “More Info” button appears next to it in the import queue. Orange buttons are warnings, which you can review and forward to support if needed. Pink buttons indicate either a header validation error or an error code from the import process.

For validation errors, click the “What went wrong” option on the error page. It gives you a short checklist to work through before contacting support. For error codes, the Import Helper (covered below) is the best way to get detailed diagnostic information.

Header Validation Errors

Header validation errors are the most common import problem. They happen when the column headings in your file don’t match what TrackEd expects. The error page shows the expected header next to the imported header so you can compare them directly, and it tells you how many rows should sit above the data set, which helps with files that have extra rows.

The most frequent cause is a stale or opened file. Always import a file freshly exported from the source system, and don’t open a Student Summary file in Excel before importing it, as that can add an extra row and trigger the error. Drag the file straight from your browser download into TrackEd, or download a fresh copy and try again.

Prep to Year 2 Student Summary exports use a separate “Student Summary P-2” import button, so check you have selected the matching import type for the year levels you are importing.

Sometimes the source system itself changes a column heading or file structure, so the expected header differs slightly from the imported one. This is not something you did wrong. See Keeping TrackEd Up to Date below, and if the difference remains after updating, screenshot the error page and send it to support@trackedapp.com.au so the team can line up the exact columns.

Importing QCAA Files

QCAA files behave differently from OneSchool files. A CSV report exported from the QCAA portal, such as Student VET or Academic Integrity Completion (AIC), often needs to be opened and resaved before it will import. Open the file in Excel, save it (saving as an .xlsx file works), close it completely, then import the resaved copy.

QCAA’s CSV exports sometimes carry encoding or formatting quirks that break TrackEd’s header validation, and resaving through Excel clears them. For the AIC report specifically, make sure TrackEd is on version 3.583 or later, as QCAA changed that file’s format.

Keeping TrackEd Up to Date

When OneSchool or QCAA changes the format of an export file, older versions of TrackEd can no longer read it and the import fails header validation. TrackEd releases a corrected version shortly after each change, so the fix is usually to update to the latest release.

Update manually from the TrackEd Downloads page, which also carries the release notes and change log, or let the server auto-update schedule handle it. After updating, export a fresh file and run the import again.

The Import Helper

For error codes or less obvious issues, click the blue “Import Helper” button in the bottom-right corner of the Import page. This generates a detailed report with logging information about what went wrong. Save the report and email it to the support team. It gives the team far more to work with than a screenshot alone. De-identify any files before sending them.

The Import Log

The Import Log (found in Settings) shows every import that has been run, including when it was processed and who ran it. A pink “Save an Excel file of log for support” button exports the full log. Set a date range and the file is saved to your TrackEd docs folder, usually on your desktop. It contains no student data, just import metadata, and helps the team diagnose recurring issues.

Resetting a Stuck Import

If an import has been running for hours (or overnight) and shows as purple in the queue with no progress, TrackEd has most likely lost its connection to the server. Go to Settings > Utilities > Reset Import Queue to clear the stuck job, then queue your files and try again.

Import Processing Settings

The Settings page has an Import Settings section in the bottom-left corner. “Send imports to server when possible” is recommended for server-hosted installations, since it sends processing to the server so you don’t have to wait at your PC. If you hit timeout issues or unusual error codes, turning it off temporarily forces imports through a different pathway, which can help isolate the problem. Turn it back on once the import completes.

“Allow DSL import to manage students” uses the Dynamic Student List to update enrolments instead of relying on Student Summary. It was added when Student Summary exports were slow for large schools; that issue is resolved, so the recommended setup leaves it off and runs Student Summary regularly. Related settings let the Absence List, Negative Behaviour import, and Personalised Learning Summary update totals and metadata (ATSI, DDA, ICP, EALD, Out of Home Care) on their own, which reduces how often you need to run Student Summary. These are generally best left off too. If you’re unsure about any import setting, check with support before changing it.

Preferred Names

Two settings control how preferred names are handled. The recommended one is “Use preferred names on profile and datawall”, which imports both legal and preferred names but only shows preferred names on outputs a student might see (profiles and datawalls). Legal names are used everywhere else in the system.

The alternative, “Import preferred names in place of legal with the DSL”, writes preferred names into the legal name field, so they show everywhere in the system. This is not the recommended setup but is there if you need it.

Ignore Lists and Roll Class Omissions

Several ignore lists let you exclude specific data during imports. The Timetable Import Subject Ignore List filters out three-digit subject codes (like tutorial periods) so they don’t appear on student profiles. The GPA Ignore List excludes codes such as instrumental music from GPA calculations, and the QCE Ignore List excludes subjects from QCE computation.

The Roll Class Omit List excludes entire roll classes. This is useful when a campus or section of your school doesn’t need to be imported into TrackEd, such as a special support campus. Add the roll class codes and they are left out during import.

Attendance Settings and Rollover Month

Attendance import settings have their own article, Attendance Data Imports Explained. The key recommendations are to enable “Absence list use alt calculation method” and to enter your local show holiday date.

The “Rollover month for absence and behaviour total” setting (recommended: 1 February) controls when the Student Summary import switches from last year’s totals to the new year’s. Import Student Summary in January and it keeps last year’s numbers, which is more useful to teachers in the first weeks of term. The first Student Summary import after the rollover date moves to the new year’s totals.

Revising Import Headers

Under Settings > Utilities, “Revise Import Headers” lets you update the expected column heading for an import when the source system has made a minor spelling change, such as an extra space or slightly different wording.

Reference

Data cleanup utilities

The Utilities page (Settings > Utilities) has cleanup options for correcting data after an import has gone wrong. Consult this table when you need to remove or reset a specific data set before reimporting.

Utility	What it does	When to use
Results Cleanup	Removes orphaned subject records and fixes subject codes showing on the wrong year-level profiles; also trims old data to keep the file small.	Duplicate results, wrong-year-level results, or a general tidy-up. See Remove Results Import.
Attendance Cleanup	Deletes attendance data from a set year and term forward so you can reimport cleanly.	Attendance percentages look wrong. See Remove Attendance Import.
Tag Cleanup	Removes previously entered tags.	Starting tags again from scratch.
Photos Cleanup	Removes photos so you can run a fresh import.	Wrong or outdated student photos.
Class Builder Cleanup / Duplicate Students	Clears class builder data and merges or removes duplicate student records.	Duplicate students or class builder issues.
Senior Schooling (VET, Task Assessments, Unit 3 & 4)	Resets senior schooling data sets and the Unit 3 & 4 progress bars.	Incorrect senior schooling data after an import.

Most schools only occasionally need Results Cleanup or System Cleanup to keep the database tidy. Tracking template imports are removed separately under Settings > Tracking Template Settings > Remove import (see Remove Tracking Template Import).

Checking Your Imported Data

After fixing an import, open a few student profiles to confirm the data landed where you expected, especially results on the correct year level and up-to-date absence totals. If something still looks off, the cleanup utilities above let you remove and reimport a specific data set. For a refresher on the import process itself, see Getting Data into TrackEd.

---

Frequently Asked Questions

Q: My OneSchool import suddenly started failing with a header or format error. What changed?
A: OneSchool has most likely changed the format of an export file, which breaks the header TrackEd expects. It is not something you did wrong. Update TrackEd to the latest release (see the TrackEd Downloads page), export a fresh file, and run the import again.

Q: Why does my QCAA CSV report (such as Student VET or AIC) fail to import?
A: Open the CSV in Excel, save it, close it completely, then import the resaved copy, as QCAA exports can carry formatting quirks that break header validation. For the AIC report, also make sure TrackEd is on version 3.583 or later. OneSchool files, by contrast, should never be opened in Excel first.

Q: I get a validation error on the Student Summary. What is the most common cause?
A: Opening the file in Excel before importing, which can add an extra row. Drag a freshly downloaded copy straight into TrackEd without opening it. For Prep to Year 2, use the separate “Student Summary P-2” import button.

Q: My import has been stuck on purple for hours. What should I do?
A: TrackEd has usually lost its connection to the server mid-import. Go to Settings > Utilities > Reset Import Queue to clear the stuck job, then queue your files and try again.

Q: Can I update the expected import header myself if a column heading has changed?
A: Only for a minor spelling change, via Settings > Utilities > Revise Import Headers. If the column order has changed, don’t update the header, as data could import into the wrong fields. Contact support instead.

Q: I imported data into the wrong year or term. How do I fix it?
A: Use the cleanup utilities in Settings > Utilities. For results, use Results Cleanup (see Remove Results Import) to remove data forward of a selected year and term, then reimport. For attendance, use Attendance Cleanup (see Remove Attendance Import).