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.

Valid syntax is not a complete model

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

roll wheel on 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 drive does not make every model animatable. The compiler must find a motion compiler for that entity, phase, 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 drive and confirm that the static model is valid.
3. Find a verified example in the same domain and compare relations and units.

Changing playback 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 use a local project file for unpublished material.