URSim can recover without a full reinstall. The direct recovery is to stop PolyScope, remove the affected URCap .jar from the hidden /home/ur/ursim-current/.urcaps directory, remove the unsupported margin keyword from the URCap source, rebuild the package, and restart with the corrected artifact.
Failure Signature and Prerequisites
Before anything else, confirm that the startup failure matches the URCap parsing problem rather than a general simulator fault.
- Start URSim from a terminal so that PolyScope messages remain visible.
- Watch the graphical progress indicator. The relevant symptom reaches 100% but does not proceed to an operable PolyScope screen.
- Read the terminal output and confirm that it identifies the unsupported HTML keyword
margin. - Identify the URCap installed immediately before the failure and locate its project source. The source must be editable before redeployment.
| Observation | Interpretation | Next action |
|---|---|---|
Terminal reports unsupported margin; loading stops at 100% |
The installed contribution blocks completion of PolyScope startup | Remove or replace that URCap archive |
| Progress remains at 100% for an extended period | The process is stalled, not completing a slow initialization | Stop waiting and begin offline recovery |
| No unsupported-keyword message appears | The documented failure signature is absent | Inspect the complete terminal output before removing components |
The reported configuration was 64-bit Ubuntu 16.04.3. The same behavior occurred with URSim 3.5.1.10661 and 3.5.0.10584. Do not move on until the terminal message, installed URCap, and source project point to the same contribution.
Blocking Archive Removal
PolyScope cannot provide its normal URCap management interface while startup is blocked. Recover access through the simulator filesystem instead.
- Stop the stalled PolyScope process. If it is attached to the active terminal, use
Ctrl+C. - Open the hidden directory
/home/ur/ursim-current/.urcaps. Enable display of hidden files if using a graphical file manager. - Locate the
.jararchive associated with the failing URCap. Match it by artifact name rather than removing every installed contribution. - Remove that archive from
.urcaps. Moving it to a separate backup location also prevents startup loading while retaining a recoverable copy. - Start PolyScope again without the affected archive.
The .urcaps directory is part of the active installation state. Uninstalling and reinstalling URSim can leave that state relevant if the same installation folder remains in use; renaming the folder worked as a broader recovery, but direct archive removal isolates the actual blocker. Confirm that PolyScope now passes the former 100% stopping point and opens normally before changing or reinstalling the URCap.
Source Correction
Remove the unsupported keyword from the UI definition before creating another package. Reinstalling the unchanged archive simply restores the same startup failure.
- Search the URCap project for
margin, including embedded HTML, generated UI resources, and style declarations packaged with the contribution. - Remove the unsupported use. Do not replace it with another styling keyword unless that keyword belongs to the HTML subset accepted by the target PolyScope environment.
- Review the complete UI resource containing the change. A second occurrence can leave the rebuilt archive defective even after the first occurrence is removed.
- Save the corrected source and run the project’s normal compilation checks.
The parser used by a constrained embedded UI does not necessarily implement every keyword accepted by a desktop browser. Browser rendering therefore is not a sufficient compatibility test for a URCap view. The required source-level confirmation is a project-wide search returning no unintended margin occurrence in the resources that enter the package.
Artifact Rebuild and Redeployment
Build a fresh artifact from the corrected source, then deploy that artifact to URSim. Keep the stopped and rebuilt states distinct so that an old archive cannot be mistaken for the fix.
| Item | Required state | Confirmation |
|---|---|---|
| UI source | Unsupported margin removed |
Source search is clean |
| URCap artifact | Rebuilt after the edit | Build completes without failure |
| URSim deployment | Corrected archive installed | Deployed file corresponds to the new build |
- With the source corrected, rebuild and upload the URCap using
mvn install -P ursimvm. - Read the Maven result and resolve any build or deployment failure before restarting PolyScope. A command invocation alone does not prove that the replacement reached URSim.
- If PolyScope was left stalled during deployment, terminate it with
Ctrl+Cafter the corrected package has been uploaded. - Restart PolyScope so that it loads the new archive from a clean process.
Do not move on until the build succeeds, the corrected artifact occupies the intended simulator deployment location, and no stale process remains running.
Clean-Start Diagnosis
The 100% indication does not prove that every installed extension initialized successfully. A startup progress bar can finish its counted loading stages before contribution parsing and UI construction return control to the application. The terminal error is therefore the decisive diagnostic signal.
| Test result | Cause path | Decision |
|---|---|---|
URSim starts after the affected .jar is removed |
The failure follows the installed URCap | Keep the archive out until rebuilt |
| Corrected archive reinstalls and URSim starts | The unsupported keyword caused the startup block | Proceed to UI functional checks |
| URSim still stalls without that archive | Another startup fault remains | Return to the terminal and identify the next reported component or resource |
| Failure returns only after redeployment | The deployed artifact is stale or still contains the unsupported resource | Recheck the package contents and build output |
Common recovery mistakes are deleting unrelated URCaps, rebuilding without saving the source edit, deploying an older artifact, and treating a browser preview as the compatibility test. Confirm causality with the remove-start-reinstall-start sequence before accepting the repair.
End-to-End Verification
- Start PolyScope from the terminal with the corrected URCap installed.
- Confirm that the progress indicator passes 100% into an operable PolyScope screen without an unsupported-
marginterminal error. - Open the function provided by the URCap and display the corrected view. Check that its controls render and remain usable without the removed styling declaration.
- Stop PolyScope normally and start it again. This second clean start proves that recovery did not depend on a leftover process state.
- Inspect the terminal during the second start and confirm both conditions: no unsupported HTML-keyword error and successful access to the URCap UI.
Do not accept a build-only result. The commissioning check is two clean PolyScope starts with the corrected URCap installed, followed by successful opening and operation of its view.
FAQ
Can I remove a URCap when PolyScope will not boot?
Yes. Stop PolyScope, open /home/ur/ursim-current/.urcaps, and remove the associated .jar archive. Restart and confirm that PolyScope passes the 100% stopping point.
Does waiting longer fix a URSim hang at 100%?
No for this failure signature. The reported startup remained stuck for an hour while the terminal identified unsupported margin; use the terminal error to begin recovery.
Can I fix the problem without reinstalling URSim?
Yes. Remove the failing archive from the hidden .urcaps directory, correct the source, and redeploy the rebuilt URCap.
Does mvn install -P ursimvm replace the broken URCap?
It rebuilds and uploads through the stated URSim Maven profile. Confirm that Maven completes successfully and restart PolyScope before judging the replacement.
Can I verify that removing margin fully fixed URSim?
Yes. Perform two clean PolyScope starts with the corrected URCap installed, confirm that the terminal no longer reports the unsupported keyword, and open the URCap view successfully on the final start.