Package Error Troubleshooting

Specific troubleshooting for SCORM package upload and processing errors.

Table of Contents

• Upload Errors
• Processing Errors
• Validation Errors
• Storage Errors

Upload Errors

Error: "No file provided"

Cause: File not included in request.

Solution:

// Ensure file is included
const formData = new FormData();
formData.append('file', file); // Required
formData.append('tenant_id', tenantId);
formData.append('uploaded_by', userId);

Error: "Invalid file type"

Cause: File is not a ZIP archive.

Solution:

• Ensure file has .zip extension
• Verify file is valid ZIP archive
• Check file wasn't corrupted during upload

Error: "File too large"

Cause: File exceeds size limits.

Solutions:

1. Check Limits:

   • Default: 100MB
   • Maximum: 10GB (multipart upload)

2. Use Multipart Upload:

   // For files >100MB
   // See: docs/getting-started/first-package.md#multipart-upload
   

3. Reduce File Size:

   • Compress media files
   • Remove unnecessary files
   • Optimize package structure

Error: "Quota exceeded"

Cause: Storage or package quota exceeded.

Solutions:

1. Check Quota:

   curl -X GET "https://app.allureconnect.com/api/customer/usage" \
     -H "X-API-Key: your-api-key"
   

2. Free Up Space:

   • Delete unused packages
   • Remove old versions
   • Archive completed packages

3. Upgrade Plan:

   • Higher plans have larger quotas
   • Contact support for custom quotas

Processing Errors

Error: "Invalid SCORM manifest"

Cause: Manifest file missing or invalid.

Solutions:

1. Verify Manifest:

   • Package must contain imsmanifest.xml
   • Manifest must be in root directory
   • Manifest must be valid XML

2. Check Manifest Structure:

   <?xml version="1.0" encoding="UTF-8"?>
   <manifest identifier="..." version="..."
     xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2">
     <!-- Valid SCORM manifest -->
   </manifest>
   

3. Validate Manifest:

   • Use SCORM validation tools
   • Check XML syntax
   • Verify namespace declarations

Error: "Missing required files"

Cause: Required files referenced in manifest are missing.

Solutions:

1. Check File References:

   • Verify all <file href="..."> files exist
   • Check file paths are correct
   • Ensure relative paths are valid

2. Verify Package Structure:

   package.zip
   ├── imsmanifest.xml
   ├── index.html
   └── assets/
       └── styles.css
   

3. Check Paths:

   • Use relative paths
   • Avoid absolute paths
   • Check case sensitivity

Error: "Unsupported SCORM version"

Cause: SCORM version not supported.

Solutions:

1. Supported Versions:

   • SCORM 1.2 ✅
   • SCORM 2004 (1st-4th Edition) ✅
   • AICC ❌ (not supported)

2. Check Manifest Version:

   <!-- SCORM 1.2 -->
   <manifest xmlns="http://www.imsproject.org/xsd/imscp_rootv1p1p2"
     xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_rootv1p2">
   
   <!-- SCORM 2004 -->
   <manifest xmlns="http://www.imsglobal.org/xsd/imscp_v1p1"
     xmlns:adlcp="http://www.adlnet.org/xsd/adlcp_v1p3">
   

3. Convert Package:

   • Use authoring tool to convert
   • Export as SCORM 1.2 or 2004
   • Re-validate after conversion

Error: "Extraction failed"

Cause: Failed to extract ZIP archive.

Solutions:

1. Verify ZIP Integrity:

   • Test ZIP file locally
   • Extract and re-zip if needed
   • Check for corrupted files

2. Check ZIP Format:

   • Use standard ZIP format
   • Avoid proprietary formats
   • Test with standard tools

3. Reduce Complexity:

   • Simplify directory structure
   • Avoid deeply nested folders
   • Limit file count

Validation Errors

Error: "Invalid launch URL"

Cause: Launch URL in manifest is invalid.

Solutions:

1. Check Launch URL:

   <resource identifier="RES-1" href="index.html">
     <file href="index.html" />
   </resource>
   

2. Verify File Exists:

   • Launch file must exist in package
   • Path must be relative
   • File must be accessible

3. Check File Extension:

   • Launch file should be HTML
   • Verify file is valid HTML
   • Check file encoding

Error: "Invalid organization structure"

Cause: Organization structure in manifest is invalid.

Solutions:

1. Check Organization:

   <organizations default="ORG-1">
     <organization identifier="ORG-1">
       <item identifier="ITEM-1" identifierref="RES-1">
         <title>Course Title</title>
       </item>
     </organization>
   </organizations>
   

2. Verify References:

   • Item identifierref must match resource identifier
   • All references must be valid
   • Check for circular references

Error: "Missing SCO definition"

Cause: SCO (Shareable Content Object) not properly defined.

Solutions:

1. Check Resource Type:

   <resource identifier="RES-1" 
             type="webcontent" 
             adlcp:scormtype="sco"
             href="index.html">
   

2. Verify SCO Type:

   • Must have adlcp:scormtype="sco"
   • Or adlcp:scormType="sco" for 2004
   • Check namespace declarations

Storage Errors

Error: "Storage upload failed"

Cause: Failed to upload to storage backend.

Solutions:

1. Check Storage Backend:

   • Verify storage is accessible
   • Check storage quota
   • Verify permissions

2. Retry Upload:

   • Wait and retry
   • Check for temporary issues
   • Verify network connectivity

3. Check File:

   • Verify file is not corrupted
   • Check file permissions
   • Ensure file is readable

Error: "Storage quota exceeded"

Cause: Storage quota limit reached.

Solutions:

1. Check Usage:

   curl -X GET "https://app.allureconnect.com/api/customer/usage" \
     -H "X-API-Key: your-api-key"
   

2. Free Up Space:

   • Delete unused packages
   • Remove old versions
   • Archive completed packages

3. Upgrade Plan:

   • Higher plans have more storage
   • Contact support for custom quotas

Package Validation Checklist

Before uploading, verify:

• File is valid ZIP archive
• Package contains imsmanifest.xml
• Manifest is valid XML
• SCORM version is supported (1.2 or 2004)
• Launch URL file exists
• All referenced files exist
• File paths are relative
• Organization structure is valid
• Resource references are correct
• Package size within limits

Testing Package Locally

Before uploading:

1. Extract and Inspect:

   unzip package.zip
   # Check structure
   ls -la
   

2. Validate Manifest:

   xmllint --noout imsmanifest.xml
   

3. Check Files:

   # Verify all referenced files exist
   grep -r "href=" imsmanifest.xml
   

4. Test in SCORM Test Suite:

   • Use ADL SCORM Test Suite
   • Validate package structure
   • Check for compliance issues

Related Documentation

• Package Validation Guide - Complete validation requirements
• Common Issues - General troubleshooting
• API Reference - Complete API docs

Last Updated: 2025-01-15