Troubleshooting

Sync Issues

Diagram not syncing to other users

Symptoms: You make changes but other users don't see them, or the sync indicator stays on "Syncing."

Steps to resolve:

1. Check your network connection — the editor works offline but needs a connection to sync
2. Look at the sync status indicator in the editor toolbar
3. Refresh the page — this forces a reconnection attempt
4. If the issue persists, the sync queue may have a failed transaction. Refreshing the page retries all pending transactions

How it works internally: Changes are stored in a sync queue in IndexedDB. Failed pushes are retried with exponential backoff. If the server rejects a transaction due to a causality violation (missing dependency), the client pulls the missing transactions and retries.

Changes appeared then disappeared

Symptoms: A shape appeared briefly then vanished.

Explanation: This can happen when a remote undo operation arrives. If another user drew something and then immediately pressed Ctrl+Z, you might see the shape appear and then get removed when the undo transaction arrives. This is normal behavior.

"Conflicting changes" after being offline

Symptoms: After reconnecting, some of your changes seem to have been overwritten.

Explanation: If you and another user modified the same property while you were offline, Last-Write-Wins (LWW) resolution applies when you reconnect. The most recent change (by timestamp) wins. Your structural changes (adding/removing shapes) are preserved — only same-property conflicts are resolved this way.

Browser Issues

Editor loads slowly on first visit

Explanation: The first load downloads the Blazor WebAssembly runtime (approximately 2MB). Subsequent loads use the browser cache and service worker, reducing startup to under a second.

Workarounds:

• Use a modern browser with good WASM performance (Chrome or Edge recommended)
• Ensure the service worker isn't blocked by browser extensions or settings

Canvas not rendering or showing a blank screen

Steps to resolve:

1. Check that your browser supports WebAssembly (all modern browsers do)
2. Disable browser extensions that might block WebAssembly or Canvas APIs (ad blockers, privacy extensions)
3. Try an incognito/private window to rule out extension conflicts
4. Clear the browser cache and reload

High memory usage with large diagrams

Explanation: Diagrams with 1000+ objects use more memory for the scene graph, spatial index, and rendering buffers.

Workarounds:

• Close other browser tabs to free memory
• Split very large diagrams into multiple smaller ones
• The spatial culling system only renders objects in the current viewport, which helps with rendering performance

Confluence Integration

Macro shows a blank or broken image

Steps to resolve:

1. Verify the DrawMotive app is installed on your Confluence site
2. Check that Forge services are operational (check Atlassian status page)
3. Re-save the diagram by clicking edit, then save again — this regenerates the PNG preview
4. Check browser console for errors related to Forge bridge communication

Editor modal doesn't open

Steps to resolve:

1. Ensure your browser allows pop-ups and modals from your Confluence domain
2. Disable browser extensions that block iframes or modals
3. Try a different browser
4. Check that you have edit permissions on the Confluence page

Diagram data lost after Confluence page migration

Explanation: Forge Storage data is tied to the macro instance. If a macro is deleted and recreated (rather than edited), the storage key changes and previous diagram data is not carried over.

Prevention: Always edit the existing macro rather than deleting and reinserting it.

VS Code Extension

.draw.png file opens as raw image instead of editor

Steps to resolve:

1. Verify the DrawMotive extension is installed and enabled
2. Check the file extension is exactly .draw.png (not .draw.PNG or .drawpng)
3. Right-click the file, select "Open With...", and choose "DrawMotive Editor"
4. Restart VS Code if the extension was recently installed

Editor not loading in VS Code webview

Steps to resolve:

1. Update VS Code to the latest version
2. Check the Output panel (View → Output → select "DrawMotive") for error messages
3. Ensure no proxy or firewall is blocking webview resource loading
4. Try disabling other extensions to check for conflicts

Constraint Solver

Shapes jump to unexpected positions when adding a constraint

Explanation: The solver minimizes total energy across all constraints. If a new constraint conflicts with existing positions, the solver adjusts all constrained shapes to find a valid configuration. This might move shapes further than expected.

Workaround: Add a Fixed Point constraint to anchor shapes you don't want to move. The solver will adjust unconstrained shapes to satisfy the new constraint while keeping anchored shapes in place.

Solver reports over-constrained system

Explanation: You've added constraints that can't all be satisfied simultaneously (e.g., a line can't be both horizontal and at 45 degrees).

Resolution: Remove one of the conflicting constraints. The solver reports which constraints are in conflict.