Troubleshooting

Troubleshooting

Start with diagnostics

npm run doctor

The base runtime and optional rendering stack are intentionally separate. A no-render workflow can work even when PDF, PNG, DXF, or office-rendering tools are unavailable.

Common outcomes

needs_review

Read qa-report.json and the stage-specific findings. This is a successful publication of reviewable evidence, not permission to ignore the finding.

blocked

Inspect the contract or configuration error in qa-report.json. A blocked run will not contain an RFQ workbook.

No burn DXF

Check for irregular parts, unplaced quantities, unsupported cutouts, or holes outside their owning rectangles. Burn output is all-or-nothing for the run.

No rendered PDF, PNG, or DXF

Install requirements-render.txt, then run the full-render tests. Use --no-render only when reference graphics are not required.

RFQ profile error

Confirm PI_STEEL_CONFIG points to a valid local JSON profile. Do not copy the completed profile into the source repository.

Before reporting a bug

Reproduce with synthetic input, include the relevant machine-readable finding, and remove local paths and business information from logs.