Diagnostics and troubleshooting

PhysLoom would rather reject an incomplete model than return a convincing but incorrect diagram. Diagnostics follow compilation stages.

Fix the first error first

One syntax error can invalidate later references. Fix the first item, then read the remaining list again. Common causes include:

• Identifier spelling differs, such as defining load and referring to Load.
• A physical quantity lacks a unit, such as mass=2 instead of mass=2kg.
• A statement references an entity or port that does not exist.
• A relation lacks a parameter required by its solver.

Apply a deterministic correction

Studio shows Apply fix only when the compiler can derive exactly one safe correction from the current language definitions and model. Click it or press Alt+Enter to apply the edit. The complete correction is one editor action, so one Undo restores the previous source.

When several corrections could be valid, Studio keeps the diagnostic as an explanation and does not guess. A correction is also discarded if the source has changed since that diagnostic was produced.

Valid syntax is not a complete model

This statement can parse, but rolling may still fail if wheel has no radius:

rolling rolling_wheel body=wheel surface=ramp mode=without_slipping

A syntax diagnostic asks whether the sentence can be read. A model diagnostic asks whether those facts define a sufficient physical system.

Do not change physics to fix layout

Overlapping objects, covered labels, and a narrow canvas are layout problems. Try another canvas width or diagram theme first. Use place only when a particular composition matters. Do not alter a rope path or connection just to make a segment look vertical.

Motion is rejected

Adding animate does not make every model animatable. The compiler must find a solver for that target and parameter set, then validate its MotionClip. If the static diagram is correct but motion is rejected:

1. Read the diagnostic for a missing parameter or unsupported boundary.
2. Remove animate and confirm that the static model is valid.
3. Find a verified example in the same domain and compare relations and units.

Changing speed or canvas size cannot fix a physical diagnostic; both affect presentation only.

Report a reproducible issue

Keep the smallest .phys source, complete diagnostics, browser version, and expected behavior. A share link places source in its URL, so send a local .phys source file for unpublished material.