SWFileFixer

Finds and repairs integrity problems in SolidWorks file corpora — broken and mis-resolved references, duplicate/mismatched internal IDs, missing configurations, and Toolbox-hardware defects.

Scanning never opens SolidWorks: assembly .SLDASM and part .SLDPRT files are read directly off disk with the SWFormat library, so a scan of tens of thousands of files costs seconds. The repair side (GUI) drives a live SolidWorks session through combridge only when a fix genuinely requires it — batch reference re-pointing, component-config changes, Toolbox flag surgery, and Toolbox size-configuration generation.

Naming note. This project began as ToolBoxFix, a Toolbox-only scanner. It was renamed to SWFileFixer on 2026-07-31 once its scope grew past Toolbox into general SolidWorks file-reference integrity and repair. The Toolbox checks remain a first-class part of it.

Quick start

Download and run — no Python, no install:

1. Grab SWFileFixer-portable.zip from Releases.

2. Unzip anywhere.

3. SWFileFixer.bat for the GUI, swfilefixer-cli.bat for the command line:

   swfilefixer-cli.bat scan "D:\Jobs\ABC"
   swfilefixer-cli.bat checks
   

Scanning is fully self-contained. Repairs additionally need SolidWorks installed (they drive a live session) and the .NET runtime the bundled combridge targets — if either is missing, scanning still works and repairs fail with a clear message.

From source: Python 3.11+, PySide6 for the GUI, and SWFormat on PYTHONPATH (or SWFILEFIXER_SWFORMAT_SRC pointed at its src/).

Screenshots

1 · Targets — point it at folders or individual files. Toolbox and weldment-profile roots are auto-detected from the SolidWorks registry.

2 · Findings — every finding carries the raw evidence that triggered it, filterable by severity, Toolbox hardware, or weldments.

3 · Repair plan — auto-built from the findings. Amber rows still need input; nothing is guessed. Preview writes nothing, and a run can be paused, resumed or cancelled between repairs.

Two options exist for the rows that are hardest to resolve by hand:

• Prefer closest name match (checkbox beside Auto-build, off by default) — when several candidate files share the missing file's internal ID, take the one whose filename is closest. This is the Pack-and-Go case: the parts were renamed with a prefix or suffix, but the saved assembly kept the old name.
• Placeholder replacement (Automation dropdown) — for a reference with no candidate at all, substitute a deliberately named empty.<name>.SLDPRT / .SLDASM stub, empty or with a small dummy body, created from your own SolidWorks template and stamped with the original path and expected file ID as custom properties. The assembly opens cleanly and names what is missing; it does not bring the geometry back, so mates to the vanished part still dangle.

Rows carry checkboxes for batch delete and for scoping automations (select-all in the header, Ctrl and Shift for ranges), and any column header sorts the plan.

Export. Both the Findings list and the Repair plan have an Export… button that writes a spreadsheet (.xlsx or .csv) — one row per finding/rule, one column per evidence field, header frozen and filters switched on. The CLI does the same with --sheet FILE. .xlsx needs the optional openpyxl extra (pip install swfilefixer[xlsx]); without it, CSV still works and opens straight into Excel.

Paths in these screenshots are pixelated where they showed real customer and contractor data.

What it finds

For every assembly in a folder tree, SWFileFixer answers these questions and emits a machine-readable report:

1. Duplicate ID for same filename — the same .SLDPRT filename exists at more than one path in your scan tree and the two files have different internal creation stamps. This is the classic "Toolbox copied into the project folder, now there are two hex bolt.sldprt files with different GUIDs" nightmare.
2. Mismatched linked ID — an assembly's saved reference to a child part records an expected creation stamp that no longer matches the file on disk. This is SolidWorks' swComponentInternalIdMismatch scenario made visible before you open the file.
3. Missing configuration — the assembly references configuration "M6 x 20" inside a target part, but that part's own configuration list does not contain that name. SolidWorks silently falls back to Default in this case, so the on-screen size and the BOM number drift without warning.
4. Toolbox flag ↔ path mismatch — a component is stored under a Toolbox root but not flagged as Toolbox (PDM/BOM tools will miss it), or is flagged as Toolbox but lives outside the Toolbox root (SW will re-resolve it against the local Toolbox root and pull a different file).
5. Name drift — the component's saved swComponentName does not match the basename of the resolved path. Common when Toolbox regenerates a filename from a template on another machine.

Each finding carries the file path, the component path, the evidence that triggered it, and a severity (data-loss, silent-drift, cosmetic).

Requirements

• Python 3.11+ (SWFormat uses @dataclass(slots=True))
• SWFormat on PYTHONPATH, or point SWFILEFIXER_SWFORMAT_SRC at your checkout's src/. (The portable release bundles it, so downloads need nothing.)
• Windows path handling — the scanner treats stored paths case-insensitively

No SolidWorks installation required. No live COM. No open file handles.

Usage

# Basic scan of a project tree
python -m swfilefixer scan D:/CustomerJobs/JobABC

# Point at your Toolbox root so the flag-vs-path check can run
python -m swfilefixer scan D:/CustomerJobs/JobABC ^
    --toolbox-root "C:/SOLIDWORKS Data/Toolbox"

# Only run a subset of checks
python -m swfilefixer scan D:/CustomerJobs/JobABC ^
    --check duplicate_ids,missing_configuration

# Write both a JSON and a human report
python -m swfilefixer scan D:/CustomerJobs/JobABC ^
    --out report.json --text report.txt

# List available checks and severities
python -m swfilefixer checks

The default output is the human-readable text summary on stdout. Add --out FILE.json for the full structured report (one finding per JSON object, plus a top-level scan manifest).

How it works — 60-second overview

walk *.SLDASM under root
    for each assembly:
        read_component_tree(asm)          # SWFormat
        extract per-component expected creation stamps  (COMPINSTANCETREE)
        for each unique referenced .SLDPRT:
            read_part_config_tree(part)   # SWFormat
            cache (creation_time, configs)
merge per-basename file registry across the whole tree
run each check() over the aggregated data
serialize findings

The heavy lifting is done by SWFormat's plain-XML mirror readers (swXmlContents/COMPINSTANCETREE on assemblies, swXmlContents/Features on parts). These are read-only mirrors of the last saved state — do not treat any finding as authoritative for a currently-open file, and never rely on SWFileFixer output for repairs that must reflect live edits.

For the deeper "why plain-XML mirrors are correct here" reasoning, see docs/ARCHITECTURE.md.

Layout

swfilefixer/
    io/          walk + read + registry (SWFormat wrappers)
    checks/      one file per check; each is a small pure function
    report/      JSON + text writers
    cli.py       argparse entry point
docs/
    ARCHITECTURE.md    why-and-how of the scanner
    CHECKS.md          one page per check, with evidence format
tests/           smoke + sanity tests
.claude/agents/  project-scoped subagent for adding new checks

Adding a new check

1. Write src/swfilefixer/checks/my_check.py — a function run(scan: Scan) -> Iterable[Finding].
2. Register it in src/swfilefixer/checks/__init__.py:REGISTRY.
3. Add a page to docs/CHECKS.md explaining why the check exists, what it inspects, and what the finding evidence means.
4. Add a smoke test in tests/.

Every new check must document its severity and its false-positive class — a check that can't articulate what a wrong flag looks like is not ready to ship.

Related projects

• SWFormat — the off-disk SolidWorks format library this depends on (Apache-2.0).
• SWBomExcluded — the sibling scanner for excluded BOM/cutlist items. Same "SWFormat as a fast off-disk pre-check, COM as the authoritative writer" pattern.

Empirical background

Failure modes were catalogued from the maintainer's field notes (the user's own field notes) and cross-checked against the recurring Toolbox threads on the SolidWorks forum, Hawk Ridge, GoEngineer, Javelin, and Reddit r/SolidWorks. Sources are cited in docs/CHECKS.md per check.

Licence

MIT — see LICENSE.

The portable release additionally redistributes CPython (PSF-2.0), PySide6/Qt and shiboken6 (LGPL-3.0), olefile (BSD-2-Clause), combridge (MIT) and SWFormat (Apache-2.0). Their licence texts ship in the bundle's THIRD-PARTY-LICENSES/ folder.