Skip to content

Operational Troubleshooting

Import errors

ModuleNotFoundError: wolfxl._rust

  • Ensure package install succeeded.
  • Verify Python environment is the one you execute from.
  • Run: python3 -c "import wolfxl._rust as m; print(m.build_info())"

Legacy import failures (excelbench_rust)

  • Install/update shim package if legacy paths are still used.
  • Prefer migrating runtime imports to wolfxl/wolfxl._rust.

Save failures

  • Confirm write or modify mode is used before save().
  • Check filesystem permissions and target path validity.

Data mismatch reports

  • Reproduce with smallest workbook possible.
  • Attach expected vs actual output and code snippet.
  • Reference Known Differences.

Comparing two workbooks without a report file

When you only need the verdict for a transformed workbook, compare the two files in memory:

wolfxl-ops compare --before source.xlsx --after target.xlsx

--policy is optional; omitting it selects the default Guard policy, which requires macros, external links, worksheets, formulas, and package integrity to be unchanged. The command prints one canonical JSON document ({"schema_version", "command", "status", "result"}) and writes no report file. result carries status, passed, issue_count, issue_codes, issue_categories, and the content hash, byte size, and filename of each input. Exit code 0 means the policy passed, 5 means the comparison was not acceptable, and 2 means an input or policy was invalid.

compare_workbooks(before, after, policy=None) returns the same immutable result from Python. Use guard-bundle instead when support needs shareable evidence written to disk.

Workbook Guard pilot support bundles

Use a support bundle when a transformed workbook fails a preservation policy and the source or output workbook cannot be shared with support.

Create a policy file with the checks required for the workflow:

{
  "macro_inventory": {"mode": "unchanged"},
  "external_link_inventory": {"mode": "unchanged"},
  "worksheet_inventory": {"mode": "unchanged"},
  "formula_integrity": {"mode": "unchanged"},
  "package_integrity": {"mode": "unchanged"}
}

Run Guard against distinct source and target files:

wolfxl-ops guard-bundle \
  --before source.xlsx \
  --after target.xlsx \
  --output support.json \
  --policy guard-policy.json

Exit code 0 means the policy passed. Exit code 5 means Guard completed but the comparison was unacceptable. Exit code 2 means the request was invalid.

support.json is a versioned document; schema_version is 2. It contains content and member digests, byte sizes, a redacted part-kind inventory with counts, the WolfXL, Python, and platform versions that produced it, a snapshot of the active policy bounds, compact policy decisions, finding categories, typed failure codes with a malformed-relationship classification, and the stable reproduction command. It excludes workbook values, formulas, part names, worksheet names, filesystem paths, and input filenames. The same inputs and policy always produce a byte-identical bundle on the same runtime. Share the JSON bundle, not the workbooks, unless a separate secure transfer has been approved.