When your LMS rejects a SCORM package: a debugging checklist

SCORM failures come in three shapes: the LMS refuses the upload outright, the module uploads but won't launch (or launches broken), or everything appears to work and then completions never show up in the gradebook. Each shape has a short list of usual suspects, and almost all of them are checkable in minutes without reading a line of the spec.

Work through this in order. The checks are sequenced from most common to least, and the first two resolve the majority of failed uploads we hear about.

Step zero: get a neutral referee

Before debugging anything, upload the package to SCORM Cloud (Rustici's testing service — free tier is fine for this). It is the closest thing the industry has to a reference implementation. The verdict splits your problem in half:

• Works in SCORM Cloud, fails in your LMS→ the package is fine; the problem is LMS configuration. Skip to the version-mismatch and completion-mapping sections below, and bring the SCORM Cloud result to your LMS admin — it changes the conversation from "your package is broken" to "let's check the activity settings."
• Fails in SCORM Cloud too→ the package itself has a problem, and SCORM Cloud's error messages are far more specific than most LMS messages. Start with the manifest checks.

Shape one: the upload is rejected

Check the manifest is at the zip root

This is the single most common failure. imsmanifest.xml must sit at the top level of the zip — not inside a folder. The classic mistake: you have a folder called my-module/ containing the manifest, you right-click the folder and compress it, and now the manifest lives at my-module/imsmanifest.xml. The LMS looks at the root, finds nothing, and reports something unhelpful like "invalid package."

To verify: open the zip and look. If the first thing you see is a single folder rather than imsmanifest.xml alongside the content files, re-zip from inside the folder (select the contents, not the folder).

Check the declared SCORM version matches what the LMS expects

The manifest declares which version of SCORM the package speaks — 1.2 or 2004 — and many LMSes make you choose a package type when creating the activity. A 2004 package uploaded into a slot configured for 1.2 (or vice versa) fails validation even though nothing is "wrong." Check both sides: what your authoring tool published, and what the LMS activity is set to accept. If you're not sure which to publish, see which SCORM version your LMS actually expects.

Check the manifest is well-formed XML

A hand-edited manifest — usually someone renaming the course title — is a frequent source of broken XML. The classic: an unescaped ampersand in a title ("Compliance & Ethics" must be written Compliance & Ethics inside the XML). Open the manifest in a browser; if the browser shows a parse error, so will the LMS.

Shape two: it uploads but won't launch, or launches broken

• Popup blockers. Many LMS players open the module in a new window. A blocked popup looks exactly like a dead package: the learner clicks Launch and nothing happens. Test with popups explicitly allowed for the LMS domain before debugging anything else — and if learners report it intermittently, this is almost always why.
• Mixed content. Your LMS is served over HTTPS; if the module references any asset — a video, a font, an image — over plain HTTP, the browser silently blocks it. Symptoms: module launches but images or video are missing. Open the browser console (F12) and look for mixed-content warnings; the fix is making every reference HTTPS or packaging the asset inside the zip.
• Case-sensitive file paths. A package built on Windows or macOS (case-insensitive filesystems) can reference Index.html while the file is named index.html. It works locally, then 404s on the LMS's Linux server. Check that the launch file named in the manifest matches the actual filename exactly, including case.
• The launch file the manifest points at doesn't exist. Usually a repackaging casualty — someone tidied the folder and moved or renamed the entry HTML file. Open the manifest, find the resource href, and confirm that path exists in the zip.

Shape three: it runs, but completions never report

The most frustrating shape, because everything looks fine. The usual suspects are all about status mapping.

Completed vs. passed

In SCORM 1.2, a module reports a single lesson_status — values include completed, passed, failed, and incomplete. Trouble starts when the module reports completed but the LMS completion rule is waiting for passed(or the reverse). SCORM 2004 splits these into separate completion and success statuses, which is cleaner but doubles the ways the mapping can disagree. Check what the module actually sends (SCORM Cloud shows you the raw calls) against what the LMS activity's completion criteria require.

Mastery score overrides

A SCORM 1.2 manifest can declare a mastery score, and many LMSes will then override whatever status the module reported, based purely on the score. So a module that reports passed with a score of 70 can be re-marked failed by an LMS honouring a mastery score of 80 sitting in the manifest — set by someone, sometime, for reasons lost to history. If statuses are being mysteriously rewritten, look for a mastery score in the manifest and in the LMS activity settings.

The closed-browser problem

SCORM data reaches the LMS when the module commits it. If a learner finishes the last screen and immediately kills the browser window, a module that only commits on exit may never get the chance — the completion evaporates. Well-behaved players commit at key moments (quiz submission, completion) rather than only at exit. If you see completions from patient learners but not from quick ones, this is your bug; the fix belongs in the authoring tool's player settings.

The checklist, condensed

• Reproduce in SCORM Cloud first — it halves the search space.
• imsmanifest.xml at the zip root, not nested in a folder.
• Declared SCORM version matches the LMS activity's expected type.
• Manifest is valid XML (watch for unescaped ampersands in titles).
• Popups allowed; no HTTP assets on an HTTPS LMS; file paths match case.
• Module's reported status (completed/passed) matches the LMS completion rule; no surprise mastery score overriding it.
• Player commits data before exit; suspend data stays within limits.

And a prevention note: most of shape one and much of shape three is packaging hygiene that a good publisher should simply never get wrong. Mltitude's eLearning modules publish to SCORM 1.2 and 2004 with the manifest, launch paths, and status mapping handled for you — and if you're still deciding how SCORM fits your stack, start with our plain-English guide to SCORM.

Keep reading