Troubleshooting

This page provides a practical starting point when BrickSuite does something unexpected. The goal is to preserve useful evidence, identify the affected workflow, and avoid making unnecessary changes while diagnosing the problem.

Troubleshoot by preserving evidence, not by resetting data until the problem disappears. If a database, CSV, backup, or log may help explain the problem, preserve it before changing or replacing it.

A Good First Response

Something unexpected happens
          |
     Stop and observe
          |
Do not delete or overwrite useful data
          |
Check the relevant Help topic
          |
Review the Application Log
          |
Can the problem be reproduced?
          |
         Yes
          |
Preserve the current log if needed
          |
       Clear Log
          |
Reproduce the problem once
          |
Review / preserve the new log
          |
Record BrickSuite version,
steps, and exact error message

See Application Log for the focused-log troubleshooting workflow.

CSV Import Problems

CSV files are structured data. A file can look correct in a spreadsheet while still containing an unexpected header, an extra field, or an extra comma that changes the number of columns in a row.

When preparing or repairing a CSV for BrickSuite, use the expected column headers for that import operation and do not add extra columns. Do not add a trailing comma to a row. A stray comma creates another CSV field and can cause the row to be rejected.

Quoted commas inside a properly formed CSV field are different from stray commas. A spreadsheet application normally handles the required quoting automatically when saving a valid CSV.

My Inventory → Import CSV

The supported owned-parts import uses these columns:

Part,Color,Quantity

Part is the Rebrickable part number, Color is the Rebrickable Color ID, and Quantity is the quantity represented by the CSV row.

BrickSuite requires every data row to contain the same number of CSV fields as the header. A trailing comma or another unintended field can produce an Invalid CSV column count error in the import preview.

See Rebrickable Import for the preview and inventory workflow.

Parts Catalog → Import Rebrickable parts.csv

The Parts Catalog importer expects the Rebrickable part fields:

part_num,name,part_cat_id,part_material

For this operation, use the official Rebrickable parts.csv file without manually adding, removing, or renaming columns. Each row must remain structurally consistent with its header.

See Parts Catalog.

Sets Catalog → Import Rebrickable sets.csv

The Sets Catalog importer requires this exact header and order:

set_num,name,year,theme_id,num_parts,img_url

The header is compared with the expected column list. Do not add, remove, rename, or reorder columns.

See Sets Catalog.

Builds → Import MOC Parts CSV

The MOC importer requires these columns:

Part,Color,Quantity

The following column is optional:

Is Spare

If Is Spare is present, BrickSuite parses its value normally. Accepted values are:

TRUE values:  true, 1, yes
FALSE values: false, 0, no

If the Is Spare column is omitted, BrickSuite imports every requirement as a regular (non-spare) requirement by default.

This supports Rebrickable custom-list exports and alternate-build workflows where the exported CSV contains Part, Color, and Quantity but does not include an Is Spare column.

Do not add a trailing comma or other unintended column to individual rows. Every row must contain the same number of CSV fields as the header.

See MOCs.

Builds → Import Pull List CSV

The Pull List importer requires this exact header and order:

Build,Set Number,Part Number,Part Name,Color,Storage Location,Quantity Allocated,Quantity Pulled

The safest workflow is to export the Pull List from BrickSuite, leave its structure and identity columns unchanged, enter the actual physical pull quantity in Quantity Pulled, save the file, and import that same CSV back into BrickSuite.

Do not add, remove, rename, or reorder Pull List columns. Do not insert an extra comma at the end of a row.

See Builds for the complete export → physical pull → import → preview → reconcile workflow.

Wrong CSV Type

Several BrickSuite workflows use CSV files, but they are not interchangeable:

Rebrickable parts.csv
  Updates Parts Catalog reference data.

Rebrickable sets.csv
  Updates Sets Catalog reference data.

Owned-parts CSV
  Adds or synchronizes physical loose inventory.

MOC Parts CSV
  Creates Build requirements.

BrickSuite Pull List CSV
  Reconciles physically pulled Build inventory.

If an importer reports an unsupported format, first verify that the file was produced for the workflow you are using.

BrickSuite Does Not Start or the Database Cannot Be Opened

Do not immediately delete or replace the BrickSuite database.
Preserve the current database if possible.
Restart BrickSuite once and review the Application Log for startup, schema, or database messages.
If recovery from a known-good backup is required, follow Backup / Restore rather than manually replacing files while experimenting.

The Expected Workspace Is Not Selected

Open Settings and verify the Default Workspace. Then confirm that the Workspace still exists and is available in BrickSuite.

Changing the default selection does not move or merge inventory between Workspaces.

I Cannot Find a Part, Set, or Inventory Record

Clear or simplify the current search text.
Check Category, Color, Year, and Storage filters as applicable.
Check the result count and paging controls.
Make sure you are searching the correct area.

Parts Catalog
  What part designs exist?

Sets Catalog
  What Sets exist?

My Inventory
  What physical loose parts do I own?

See Parts Catalog, Sets Catalog, and My Inventory.

Part or Set Images Are Missing

Reference images may need time to download and populate the local cache. Confirm that the computer has network access and allow background image activity to continue. If appropriate, open the item's Details view and then recheck the image.

If images continue to fail, review the Application Log for image/network warnings before changing cache files manually.

A Rebrickable Inventory Import Does Not Look Correct

Stop at the Import Preview if the result is unexpected.
Verify that the selected file is an owned-parts CSV.
Verify the destination Storage location, Condition, and Ownership settings.
Check the CSV header and row column counts described above.
Review rows marked with an Error or review status before importing.

Preview is intentionally the point where you can cancel without committing inventory changes.

A Build Shows Unexpected Missing Quantities

Review the requirement columns rather than looking only at Owned quantity:

Owned
This Build
Other Builds
Available
Missing

A piece can be owned by the Workspace but unavailable to the current Build because it is already allocated elsewhere. Use Allocate Available and Missing Parts to understand the current state.

Allocate Available Does Not Allocate Anything

This can be normal when:

the requirements are already fully allocated;
no matching loose inventory remains available;
matching inventory is reserved by another Build; or
the requirement no longer needs additional allocation.

Manual allocation and Allocate Available use the same allocation model. Review the requirement quantities before assuming the operation failed.

The Pull List Does Not Match What I Physically Pulled

Stop at the reconciliation preview. No database changes have been made at that point.

Compare Quantity Allocated with the actual Quantity Pulled, correct the physical pull or CSV if needed, then preview it again. Reconcile only when the preview represents what actually happened.

Physical Inventory Does Not Match BrickSuite

Use the workflow that represents what physically happened:

Edit
  Maintain an inventory record or quantity.

Move
  Physically relocate pieces and preserve movement history.

Lost
  Record pieces that BrickSuite expected but you cannot locate.

Found / Return
  Return previously lost inventory when it is recovered.

Avoid deleting history or making unrelated quantity changes simply to make the totals match. See My Inventory and Lost / Found.

Backup or Restore Reports a Failure

Preserve both the current database and the backup file. Do not repeatedly overwrite either file while experimenting.

Review the Application Log and follow Backup / Restore for the supported workflow.

Theme or Display Looks Wrong

Review the Theme under Settings → Appearance. If a display problem persists after selecting the intended theme, restart BrickSuite and recheck it before making more invasive changes.

Before Asking for Support or Opening an Issue

A good problem report makes an issue much easier to reproduce and diagnose. Record:

BrickSuite version:
What I was doing:
What I expected:
What happened instead:
Exact error message:
Can I reproduce it:
Steps to reproduce:
Relevant Application Log entries:
Screenshot, if useful:
CSV or backup involved, if relevant:

The BrickSuite version is available from Help → About BrickSuite. If a CSV caused the problem, preserve the original file rather than editing the only copy before the problem is understood.

Protect private information. Before sharing screenshots, logs, CSV files, or other diagnostics publicly, review them for API keys, personal paths, private inventory data, or other information you do not intend to publish.