Troubleshooting¶

Common issues and solutions for MapBoot Editor and Viewer.

Quick Diagnostics¶

Start here for fast diagnosis:

Enable Debug Mode (Editor toolbar) — Shows connection counts on points
Use Preview Mode (Editor toolbar) — Hides gizmos to view graphics clearly
Publish and Test in Viewer — Preview mode doesn't test routing; publish and use actual viewer
Check Browser Console (F12) — Reveals JavaScript errors
Verify Map is Published — Saved ≠ Published

Routing Problems¶

No Route Found Between Locations¶

Symptoms: - "No route found" message - Route won't generate between two locations

Likely Causes: 1. Access points not defined on one or both locations 2. Access points not connected to routing network 3. Routing network has gaps 4. Locations on different floors without transitions 5. Locations in different buildings without outdoor path connections

Diagnosis: 1. Enable Debug mode 2. Check each location's access points have 2+ connections on routes sub-layer 3. Verify routing lines on routes sub-layer connect access points 4. If multi-floor: verify transitions exist 5. If multi-building: verify outdoor paths connect buildings

Fixes: - Add access points to locations on routes sub-layer (via Properties → Access Points → Pick) - Draw routing lines on routes sub-layer to connect access points - Ensure routes network is continuous (no gaps) - Twin transition access points across floors - Add outdoor paths between buildings on transit group routes layer

Route Goes the Wrong Way¶

Symptoms: - Route takes a long detour - Route uses distant entrance instead of nearby entrance - Route backtracks unnecessarily

Likely Causes: 1. Missing routing shortcut on routes layer 2. Alternate path is shorter in graph distance 3. Access point not connected to nearby routing on routes layer

Fixes: - Add missing routing lines for realistic shortcuts on routes layer - Adjust routes geometry to reflect real walking distances - Ensure all access points connect to nearest paths on routes layer - Remove unintended routing lines that create false shortcuts

Route Appears to Go Through Walls¶

Symptoms: - Route appears to pass through walls visually

Likely Causes: 1. Routes layer and graphics layer are misunderstood - they're separate 2. Routes intentionally pass through doorways/openings that aren't visible in graphics

Explanation: - Graphics layer (walls) and routes layer (pathfinding) are completely separate - Routes are drawn on their own layer and pass through accessible areas - Visual walls don't block routes - routes define walkability independently

This is usually correct behavior - routes pass through doorways and entrances even though walls appear continuous on the graphics layer.

Route Uses Wrong Transition¶

Symptoms: - Route uses distant elevator/stairs instead of nearby one - Route chooses suboptimal transition

Likely Causes: 1. Distant transition is "shorter" in graph distance 2. Nearby transition not properly connected 3. Routing network makes distant transition more efficient

Diagnosis: - Test route in preview mode - Check both transitions show in Debug with 2+ connections - Trace the actual graph distance for both paths

Fixes: - Adjust routes network to reflect real walking distances - Ensure nearby transition access point is fully connected on routes layer - Consider if the "wrong" transition is actually optimal from the router's perspective - Add more routing detail near transitions on routes layer

Display Issues¶

Blueprint Alignment Problems¶

Symptoms: - Blueprint doesn't align with geometry - Floors don't align vertically in multi-floor buildings - Blueprint is wrong size

Fixes: 1. Wrong Scale: - Select layer in tree - In Properties, adjust "Background Scale" - Use a known distance to calibrate

Misaligned Across Floors:
Pick fixed reference points (elevator shafts, columns)
Ensure same XY coordinates across all floors
May need to redraw transition points at correct positions
Blueprint Positioned Wrong:
Drag blueprint in viewport to reposition
Use reference points to align

Surfaces Don't Fill (Polygons)¶

Symptoms: - Polygon style applied but area doesn't fill - Partial fill or holes in surface - Unexpected polygon shapes

Likely Causes: 1. Line loop not closed — micro-gap exists 2. Overlapping points instead of shared vertices 3. Self-intersecting geometry

Fixes: 1. Zoom in close to verify all endpoints truly connect 2. Enable Snap, move points to create real connections 3. Delete duplicate points at same location 4. Reapply polygon style after fixing geometry 5. Use Debug mode to inspect point connections

Walls Look Jagged or Messy¶

Causes: - Drawing without Snap enabled - Freehand drawing without grid alignment

Fixes: - Enable Snap to Grid - Zoom in while drawing for precision - Redraw problematic walls with Snap on - Use grid squares for straight walls

Location Labels Overlap¶

Causes: - Too many locations in small area - Location markers positioned poorly

Fixes: - Drag location markers to better positions - Reduce number of locations (combine similar ones) - (Feature request: Label collision detection - contact support)

Search & Location Issues¶

Location Not Found in Search¶

Symptoms: - Location doesn't appear when searched - Location exists but is not searchable

Likely Causes: 1. No name filled in 2. Map not published (only saved) 3. Poor metadata (doesn't match search terms) 4. Location created on graphics layer (automatically deleted)

Fixes: 1. Select location, verify Name field is filled 2. Publish the map (not just save) 3. Add relevant Meta Data keywords 4. Use clear, searchable names 5. Ensure location was created on the routes layer (location points can only exist on routes layer)

Location Highlights Wrong Area¶

Symptoms: - Searching location highlights incorrect surface - Surface doesn't match location

Likely Causes: 1. Wrong surface assigned to location 2. Surface assigned to multiple locations

Fixes: 1. Select location 2. In Properties → Surfaces, verify correct polygons assigned 3. Remove incorrect surfaces, add correct ones

Location Disappeared After Creating It¶

Symptoms: - Created a location marker but it vanished - Can't find the location point you just created

Likely Causes: - Location was created on the graphics layer instead of routes layer - Orphan points on graphics layer are automatically deleted

Fixes: 1. Switch to the routes layer 2. Create the location marker again on routes layer 3. Press Esc to create orphan point 4. Remember: locations can only exist on the routes layer

Can't Route to Location¶

Symptoms: - Location appears in search - Can't generate route to it

Likely Causes: 1. No access points defined 2. Access points not connected to routing network

Fixes: 1. Select location 2. In Properties → Access Points, add at least one entrance on routes network 3. Verify access point has 2+ connections in Debug mode 4. Draw routing lines to connect access point to network

Multi-Floor Issues¶

No Route Between Floors¶

Symptoms: - Can route within each floor - Can't route between floors

Likely Causes: 1. Transitions not twinned 2. Transition points not in routing network 3. Missing transition entirely

Diagnosis: 1. Multi-select the two floors (Ctrl+Click) 2. Look for dashed arrows between floors 3. If no dashed arrows, transitions not created 4. Enable Debug, check transition points have 2+ connections on each floor

Fixes: 1. Multi-select the floors 2. Pick transition access point on first floor 3. Use Twins → Pick to select matching point on second floor 4. Verify dashed arrow appears 5. Ensure both points connect to routing networks

Transition Appears in Wrong Location¶

Symptoms: - Elevator/stairs marker appears in wrong spot when switching floors - Vertical alignment is off

Likely Causes: - Blueprints misaligned across floors - Transition points at different XY coordinates

Fixes: 1. Re-align blueprints using fixed reference points 2. Note correct XY coordinates for transition 3. Move transition access points to matching coordinates on all floors 4. Re-twin the transitions

One-Way Transition When Should Be Two-Way¶

Symptoms: - Can go from Floor 1 to Floor 2 - Can't go from Floor 2 to Floor 1

Likely Causes: - Twin missing in one direction

Fixes: 1. Select transition point on Floor 2 2. In Properties → Twins, verify Floor 1 point is listed 3. If not listed, re-twin from Floor 2 to Floor 1

Multi-Building Issues¶

No Route Between Buildings¶

Symptoms: - Each building works independently - Can't route from Building A to Building B

Likely Causes: 1. No Transit group created 2. Outdoor paths don't connect buildings 3. Building entrances not twinned to outdoor network

Diagnosis: 1. Verify Transit group exists (type: Transit) 2. Check outdoor paths layer has continuous network 3. Multi-select building floor + outdoor layer 4. Look for dashed arrows from building to outdoor 5. Verify outdoor network connects all building entrance points

Fixes: 1. Create Transit group (type: Transit) 2. Add layer with outdoor paths 3. Set sub-layer to Routes and draw routing lines connecting all buildings 4. Multi-select building floor + outdoor layer 5. Twin building entrance to outdoor connection point 6. Repeat for all buildings

Route Uses Wrong Building Entrance¶

Symptoms: - Route exits distant door instead of nearby door

Likely Causes: - Outdoor path geometry makes distant entrance "shorter" - Nearby entrance not properly connected

Fixes: - Adjust outdoor path geometry to reflect real distances - Verify nearby entrance is twinned and connected - Test if "wrong" entrance is actually optimal in graph distance

Embedding & Viewer Issues¶

Nothing Renders / Blank Map¶

Symptoms: - Container shows but map is blank - No error in console

Likely Causes: 1. Map not published (only saved) 2. Wrong Map ID 3. Container has no height

Fixes: 1. Ensure map is Published in editor 2. Verify Map ID matches exactly (copy-paste to be sure) 3. Set explicit height on container:

HTML

<div id="mapboot" style="height: 600px;"></div>

4. Check browser console for errors (F12)

CORS / Cross-Origin Error¶

Symptoms: - Console error: "Access-Control-Allow-Origin" - Map fails to load

Likely Causes: - Domain not whitelisted

Fixes: 1. In Editor, select Map (top of tree) 2. In Properties → Allowed Domains, add your domain - Use just domain: example.com (not https://example.com/page) 3. Save and Publish 4. Clear browser cache and refresh

Map Shows Old Version¶

Symptoms: - Changes made in editor don't appear in embedded map

Fixes: 1. Ensure you clicked "Publish" (not just "Save") 2. Hard refresh browser: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac) 3. Clear browser cache 4. Check CDN caching (may take a few minutes)

Collaboration Issues¶

Collaborator Can't See Map¶

Likely Causes: 1. User not registered/confirmed 2. No floors assigned to collaborator

Fixes: 1. Verify collaborator has confirmed MapBoot account 2. Assign at least one floor to them: - Select layer in tree - In Properties, add their email to Collaborator Email - Save

Collaborator Can't Edit Floor¶

Likely Causes: - Floor not assigned to them - Floor assigned to someone else

Fixes: - Owner must assign floor specifically to this collaborator - Check floor Properties → Collaborator Email field

Can't Create Transition Across Collaborator Floors¶

Likely Causes: - Transitions across floors owned by different collaborators must be created by Owner

Explanation: - Collaborators can only twin transitions between their own assigned floors - Owner must handle cross-ownership transitions

Performance Issues¶

Editor is Slow / Laggy¶

Likely Causes: 1. Very large/complex map 2. Too many points/lines 3. Browser running out of memory

Fixes: - Simplify geometry (remove unnecessary detail) - Work on one floor at a time - Close other browser tabs - Use a more powerful computer for complex maps - Consider splitting very large facilities into multiple maps

Viewer Loads Slowly¶

Likely Causes: - Large map size - Slow user connection

Fixes: - Optimize map complexity in editor - Ensure reasonable polygon counts - Consider using lower-resolution blueprints - Contact support about performance optimization options

Data Loss & Recovery¶

Lost Unsaved Work¶

Symptoms: - Browser crashed or refreshed - Changes disappeared

Prevention: - Save frequently (Cmd/Ctrl+S) - Save after each major change - Use "Save All" button regularly

Recovery: - Unfortunately, no auto-save or version history - Unsaved work cannot be recovered - Always save before closing or navigating away

Accidentally Deleted Geometry¶

Symptoms: - Deleted wrong element - Want to undo deletion

Fixes: - Undo immediately: Cmd/Ctrl+Z - Undo only works for current session - If you saved after deletion, cannot recover (must redraw)

Debug Mode Reference¶

What Debug Mode Shows: - Numbers on points — Connection count - Viewport debug log — Map statistics and diagnostics

How to Use: 1. Click Debug button in toolbar 2. Look at points: - 0 = Isolated (not connected to anything) - 1 = Dead end (only one connection) - 2 = Normal connection (line passing through) - 3+ = Junction (multiple lines meet)

Interpreting Numbers: - Door points should show 2+ (wall line + routing line) - Access points should show 2+ (connected to routing network) - Transition points should show 2+ on each floor - Orphan location points show 0 (this is normal)

Getting Additional Help¶

Before Contacting Support¶

✅ Check this troubleshooting guide
✅ Review Core Concepts
✅ Check relevant workflow guide
✅ Enable Debug mode and inspect the issue
✅ Use Preview mode to view graphics clearly (hides gizmos)
✅ Publish and test routing in actual viewer (not editor preview)
✅ Check browser console for errors

When Contacting Support¶

Include: - Map ID - Specific locations or floors affected - Steps to reproduce the issue - Screenshots (especially Debug mode view) - Browser console errors (if any) - What you expected vs. what happened

Email: contact@mapboot.com

Common Error Messages¶

"Route not found"¶

→ See No Route Found Between Locations

"Access-Control-Allow-Origin"¶

→ See CORS / Cross-Origin Error

"Map not published"¶

→ Click Publish button in Editor toolbar

"Invalid Map ID"¶

→ Verify Map ID is correct, copied exactly from Map Properties

Quick Reference: Diagnostic Checklist¶

Text Only

Routing Issues:
□ Locations have access points
□ Access points have 2+ connections (Debug)
□ Routing lines drawn on Routes sub-layer
□ Routing network is continuous
□ Transitions twinned (if multi-floor/building)

Display Issues:
□ Blueprint scale is correct
□ Polygons are closed loops
□ Wall lines have wall styles
□ Geometry is clean (no overlaps/gaps)

Search Issues:
□ Location has a name
□ Map is published
□ Location has access points
□ Access points are connected

Embedding Issues:
□ Map is published
□ Map ID is correct
□ Domain is whitelisted
□ Container has height
□ Check browser console for errors

Still stuck? Email contact@mapboot.com with details.