Skip to main content
This guide covers common issues you might encounter while using Gitlantis and how to resolve them.

​
Project Loading Issues

Problems related to loading your project in Gitlantis.
Error Type: no-project-open (from DIRECTORY_ERRORS.no_open_project)Symptoms:
  • Gitlantis shows “You have no active project open at the moment”
  • The ocean is empty with no files or folders
Causes:
  • No workspace folder is open in VS Code
  • The workspace folder path is invalid or cannot be found
Solution:
  1. Open a folder in VS Code: File > Open Folder
  2. Select your project directory
  3. Restart Gitlantis or reload the webview
  4. The project should now appear in the ocean
See src/extension/handlers/readDirectory/index.ts:38-46 and src/extension/config/index.ts:19.
Error Type: no-project-open (generic fallback)Symptoms:
  • Error message: “There was a problem loading your project”
  • Files and folders don’t appear
Causes:
  • File system permissions issues
  • Corrupted workspace metadata
  • VS Code API errors
Solution:
  1. Check file system permissions for the project folder
  2. Try closing and reopening VS Code
  3. Verify the workspace folder path is valid
  4. Check VS Code’s Output panel for additional error details
  5. Try opening a different project to isolate the issue
See src/extension/handlers/readDirectory/index.ts:37-46.
Error Type: vscode-api-error (from DIRECTORY_ERRORS.vscode_api_error)Symptoms:
  • Communication between the extension and webview fails
  • Commands don’t work (file opening, directory navigation)
Causes:
  • Extension host crashed or restarted
  • Webview lost connection to the extension
  • VS Code extension API is unavailable
Solution:
  1. Reload the VS Code window: Developer: Reload Window
  2. Check if other extensions are causing conflicts
  3. Disable other extensions temporarily to test
  4. Update VS Code to the latest version
  5. Reinstall Gitlantis if the issue persists
See src/extension/config/index.ts:18.

​
File and Folder Interaction Issues

Problems when trying to open or navigate files and folders.
Symptoms:
  • Pressing Shift+Enter does nothing
  • Error message: “Cannot open the file at: [path]”
Causes:
  • File has been deleted or moved
  • Insufficient permissions to read the file
  • File path is invalid or contains special characters
  • Not in collision range with the file object
Solution:
  1. Make sure you’re close enough to the file (collision detection active)
  2. Verify the file still exists in the file system
  3. Check file permissions (read access required)
  4. Try refreshing the directory view (go back and re-enter)
  5. Check for special characters in the file path that might cause issues
See src/extension/handlers/openFile/index.ts:3-10.
Symptoms:
  • Shift+Enter, Escape, or other shortcuts have no effect
  • Keys seem unresponsive
Causes:
  • Focus is not on the Gitlantis webview
  • Shortcuts are disabled in settings
  • Key event listeners are not attached
  • Another extension is intercepting the keys
Solution:
  1. Click on the Gitlantis webview to ensure it has focus
  2. Check that shortcuts are enabled in settings
  3. Verify you’re in collision range with an object (for Shift+Enter)
  4. Try reloading the webview
  5. Disable other extensions that might intercept keyboard events
  6. Check browser console for JavaScript errors
See src/browser/hooks/useNode/shortcuts/index.ts:95-106.
Symptoms:
  • Can’t open files even when next to them
  • Shortcuts work but select the wrong object
Causes:
  • Collision state ref is not initialized
  • Physics engine issues
  • Object positions are out of sync
Solution:
  1. Sail away from the object and approach again
  2. Reload the webview to reset collision state
  3. Check for console errors related to collision detection
  4. Verify the object is loaded (visible in the scene)
  5. Try using the minimap to navigate to a different area and back
See src/browser/hooks/useNode/shortcuts/index.ts:23-29.
Problems with boat controls and navigation.
Symptoms:
  • WASD or arrow keys don’t move the boat
  • Boat is stuck in place
Causes:
  • Keyboard event listeners not attached
  • Focus is on another element
  • JavaScript errors preventing movement code
Solution:
  1. Click on the Gitlantis webview to restore focus
  2. Check browser console for errors
  3. Reload the webview
  4. Try pressing different movement keys (W, A, S, D, or arrows)
  5. Verify settings haven’t disabled movement
See src/browser/hooks/useBoat/keyboard/index.ts:8-70.
Symptoms:
  • Navigation is uncomfortably fast or slow
  • Hard to control the boat precisely
Causes:
  • Boat speed settings are not optimal for your preference
  • Acceleration/deceleration settings need adjustment
Solution:
  1. Open Gitlantis settings
  2. Adjust the boat speed setting
  3. Fine-tune acceleration and deceleration for better control
  4. Test different values until comfortable
See Customizing Your Boat for detailed configuration.
Symptoms:
  • No minimap visible on screen
  • F key doesn’t toggle minimap
Causes:
  • Minimap is disabled in settings
  • Splash screen is still showing
  • Opacity transition hasn’t completed
Solution:
  1. Check settings and set minimap to “Show”
  2. Wait for splash screen to fade (1700ms delay)
  3. Look for the minimap toggle button in the top-right corner
  4. Try pressing F to toggle fullscreen mode
  5. Reload the webview if minimap still doesn’t appear
See src/browser/components/world/minimap/toggle.tsx:11 and src/browser/components/world/minimap/index.tsx:17-19.
Symptoms:
  • Compass shows wrong direction
  • Direction doesn’t update when turning
Causes:
  • Boat ref is not initialized
  • Update interval is broken
Solution:
  1. Reload the webview to reinitialize the compass
  2. Check browser console for errors
  3. Verify the boat is loaded and visible
  4. Try moving the boat to trigger compass updates
See src/browser/hooks/useBoat/compass/index.ts:9-22.

​
Performance Issues

Problems with frame rate, lag, or responsiveness.
Symptoms:
  • Choppy animation
  • Delayed response to keyboard input
  • Slow rendering
Causes:
  • Large project with many files/folders
  • Computer hardware limitations
  • Other resource-intensive programs running
Solution:
  1. Close other applications to free up resources
  2. Navigate to smaller subdirectories instead of the root
  3. Reduce visual effects in settings:
    • Lower bobbing/rocking amplitude
    • Simplify boat colors (solid colors perform better)
  4. Update graphics drivers
  5. Increase hardware acceleration in VS Code settings
See src/browser/hooks/useBoat/navigation/index.tsx:48 for delta time handling.
Symptoms:
  • Boat movement is jerky
  • Inconsistent frame times
Causes:
  • Directory loading happening in the foreground
  • Too many collision checks
  • Frame rate drops during physics calculations
Solution:
  1. Wait for directory loading to complete before moving
  2. Navigate to folders with fewer items
  3. Disable other VS Code extensions temporarily
  4. Check Task Manager / Activity Monitor for high CPU usage
  5. Consider upgrading hardware if the issue persists
The navigation system uses delta time multiplier capped at 2x to prevent extreme jumps. See src/browser/hooks/useBoat/navigation/index.tsx:48.

​
General Troubleshooting Steps

If you encounter an issue not listed above:
1

Check Browser Console

Open the browser developer tools in the webview:
  1. In VS Code, open Help > Toggle Developer Tools
  2. Look for error messages in the Console tab
  3. Note any red error messages or warnings
2

Reload the Webview

Refresh Gitlantis to reset the state:
  1. Close the Gitlantis webview panel
  2. Reopen Gitlantis from the command palette
  3. Wait for the project to load completely
3

Reload VS Code

Restart the entire VS Code window:
  1. Open the Command Palette (Cmd/Ctrl+Shift+P)
  2. Run Developer: Reload Window
  3. Wait for VS Code to restart
  4. Open Gitlantis again
4

Check for Updates

Ensure you’re running the latest version:
  1. Open the Extensions panel
  2. Search for Gitlantis
  3. Check if an update is available
  4. Update and reload if necessary
5

Report the Issue

If the problem persists:
  1. Note the exact steps to reproduce
  2. Capture any error messages
  3. Check the Gitlantis GitHub repository for known issues
  4. File a bug report with detailed information

​
Error Type Reference

Quick reference for error types defined in the source code:

vscode-api-error

Communication failure between extension and webview

no-project-open

No workspace folder is open or can’t be found

generic

General error not categorized elsewhere
See src/extension/config/index.ts:17-21 for error constant definitions.

Build docs developers (and LLMs) love

Get started for freeTalk to us