Import Troubleshooting

TL;DR: Most issues = missing BSA IDs or wrong export format. Use ScoutBook+ "Custom Roster Report" with all boxes checked.

Quick Reference

File Errors

Invalid file format

Causes: Not CSV, corrupted download, encoding issues

Fix:

• Verify file extension is .csv
• Open in Excel/Sheets to test
• Re-export from BSA system
• Clear browser cache and re-download

Missing required column

Causes: Wrong export type, incomplete options

Fix:

• ScoutBook+: Use "Custom Roster Report" (NOT Report Builder)
• Check all boxes: BSA Member IDs, Phone numbers, Adult/Scout options
• Verify column headers exist in first row

Member Matching

All members show as "New" (should be "Update")

Causes: BSA Member IDs missing or mismatched

Fix:

1. Check CSV has "Member ID" column with 9-digit numbers
2. Verify existing members in TroopBook have BSA IDs populated
3. If missing in TroopBook, add manually then re-import

Duplicate members created

Fix:

1. Find which record has correct BSA ID
2. Transfer missing data to correct record
3. Delete duplicate (Members → Detail → Remove)

Relationships

Missing parent-child relationships

Causes:

• ScoutBook+: Parent BSA IDs missing, "Adult options" not checked
• ScoutBook Legacy: Parent emails don't match between files
• My.Scouting: Not supported (no parent data exported)

Fix:

• ScoutBook+: Re-export with "Adult options" and "Scout options" checked
• ScoutBook Legacy: Verify parent email matches adult email exactly
• My.Scouting: Add relationships manually after import

Incorrect relationships

Fix:

• Member detail page → Relationships → Remove (X icon)
• Fix source data in BSA system, re-export
• Use ScoutBook+ for reliable matching (uses BSA IDs, not emails)

Units

Units not created

Causes: "Create Units" disabled, or no unit data in export

Fix:

• Enable "Create Units" checkbox
• Verify den/unit columns in CSV have values
• My.Scouting: Manually create units (no unit data exported)

Duplicate units

Fix:

1. Check "Units to Enrich" section in preview (should update, not create)
2. If database error occurs, delete duplicate manually (Units → Detail → Delete)
3. Re-import

Data Quality

"X youth without grade assignments" (Kindergarten/Lion)

Known Bug: ScoutBook+ and My.Scouting export blank grades for Kindergarteners

ScoutBook+: Auto-inferred from Lion den ✅ No action needed

My.Scouting:

• Option 1: Edit CSV, add "Kindergarten" to GradeName column
• Option 2: Import, then manually create Lion Den and assign members

"X youth have no parent email"

Fix:

• Add parent contact in BSA system, re-export
• Or manually add in TroopBook (Youth → Edit Contact Info)
• Or use ScoutBook+ which includes parent data

"X adults have incomplete addresses"

Fix:

• Update in BSA system, re-export
• Or manually add in TroopBook (Adults → Edit Contact Info)

Import Execution

Import fails mid-execution

Causes: Network interruption, timeout on large imports

Fix:

1. Check what was imported (Members → All Members)
2. Re-import with "Update Existing" enabled
3. TroopBook skips already-imported members (matched by BSA ID)
4. For large rosters (500+), split into smaller files

Database constraint error

Message: "duplicate key value violates unique constraint idx_units_external_ref_unique"

Cause: Trying to create unit that already exists with same external reference

Fix:

1. Check existing units (Units → All Units)
2. Delete duplicate if has no members
3. Re-import (should match and enrich instead of create)

Prevention Checklist

• Exported from correct BSA system
• Used correct export format (Custom Roster Report for ScoutBook+)
• Checked all export options (BSA IDs, phone, adult/scout options)
• File is CSV format
• Opened in Excel/Sheets to verify data
• BSA Member IDs column has 9-digit numbers
• Reviewed import preview before executing
• Verified member counts match expectations

Still Stuck?

Gather info:

• Screenshot of error message
• Screenshot of import preview
• Export source (ScoutBook+, My.Scouting, Legacy)
• Number of members in file

Check these guides:

• Understanding Import Preview →
• Import Options →
• ScoutBook+ Export Guide →