metaverseDubai/docs/troubleshooting/TROUBLESHOOTING.md

Troubleshooting Guide - Dubai Metaverse

Common Issues and Solutions

Installation Issues

GitHub Access Denied

Problem: Cannot clone Unreal Engine repository

fatal: could not read Username for 'https://github.com'

Solution:

1. Link GitHub account to Epic Games: https://www.unrealengine.com/en-US/ue-on-github
2. Sign in with Epic Games account
3. Link GitHub account
4. Accept Unreal Engine license
5. Try cloning again

Alternative: Use SSH instead of HTTPS (requires SSH key setup)

.NET SDK Not Found

Problem: Package 'dotnet-sdk-6.0' has no installation candidate

Solution (Ubuntu 24.04):

sudo add-apt-repository -y ppa:dotnet/backports
sudo apt update
sudo apt install -y dotnet-sdk-6.0

Alternative: Install dotnet-sdk-8.0 if 6.0 not available

Build Fails Due to Low RAM

Problem: Build process killed, out of memory errors

Solutions:

1. Reduce parallel jobs: make -j2 UnrealEditor (instead of -j4)
2. Close other applications
3. Add swap space:

   sudo fallocate -l 16G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   

4. Edit script: Change NUM_CORES=4 to NUM_CORES=2

Tag Not Found

Problem: fatal: Remote branch 5.4.1 not found

Solution: The script should handle this automatically by falling back to 5.4 branch. If not:

cd ~/UnrealEngine
git fetch --depth=1 origin tag 5.4.1
git checkout 5.4.1

Or use the branch instead:

git clone --depth=1 https://github.com/EpicGames/UnrealEngine.git -b 5.4 UnrealEngine

WSL Graphics Issues

Editor Won't Launch

Problem: Unreal Editor won't start in WSL

Solutions:

1. Check DISPLAY variable:

   echo $DISPLAY
   # Should show something like :0 or IP:0.0
   

2. Set DISPLAY for WSL2:

   export DISPLAY=$(ip route list default | awk '{print $3}'):0.0
   # Add to ~/.bashrc to make permanent
   

3. Verify X Server is running (Windows 10):

   • Install VcXsrv or Xming
   • Start X server with "Disable access control"
   • Check X server is listening

4. Test X connection:

   sudo apt install x11-apps
   xeyes  # Should open a window
   

WSLg Not Working (Windows 11)

Problem: WSLg not displaying GUI applications

Solutions:

1. Update WSL: wsl --update (from Windows PowerShell)
2. Restart WSL: wsl --shutdown then restart
3. Check WSLg: echo $DISPLAY should show :0
4. Verify Windows 11 version supports WSLg

Project Issues

Project Won't Open

Problem: Unreal project fails to open

Solutions:

1. Verify project file (.uproject) is valid JSON
2. Check project is compatible with UE5.4
3. Regenerate project files:
   • Right-click .uproject > Generate Visual Studio files (Windows)
   • Or use UnrealVersionSelector (Linux)
4. Check engine association in .uproject file

Engine Features Not Working

Problem: Nanite, Lumen, or other features not working

Solutions:

1. Verify features enabled in Project Settings
2. Check GPU supports required features
3. Update to latest engine version
4. Check project settings: docs/setup/PROJECT_SETTINGS.md

Performance Issues

Problem: Low FPS, stuttering, or lag

Solutions:

1. Update GPU drivers
2. Check system meets requirements
3. Lower viewport quality settings
4. Disable unnecessary plugins
5. See Performance Optimization

Script Issues

Script Permission Denied

Problem: Permission denied when running script

Solution:

chmod +x scripts/script_name.sh
./scripts/script_name.sh

Script Fails with Error

Problem: Script exits with error code

Solutions:

1. Check script logs: logs/script_name.log
2. Run with verbose output: ./scripts/script_name.sh --verbose
3. Check prerequisites are met
4. Review script documentation

Python Script Import Error

Problem: ModuleNotFoundError: No module named 'X'

Solution:

pip install -r requirements.txt

Version Control Issues

Git LFS Not Working

Problem: Large files not tracked by Git LFS

Solutions:

1. Install Git LFS: git lfs install
2. Verify .gitattributes file exists
3. Check file types are tracked in .gitattributes
4. Re-add files: git add --renormalize .

Large File Push Fails

Problem: Push fails due to large files

Solutions:

1. Ensure Git LFS is installed and configured
2. Check .gitattributes includes file types
3. Verify Git LFS is tracking files: git lfs ls-files
4. Check repository size limits

Build and Packaging Issues

Build Fails

Problem: Project build fails

Solutions:

1. Clean build: Delete Binaries/ and Intermediate/ folders
2. Regenerate project files
3. Check for compilation errors in logs
4. Verify all dependencies are installed
5. Check project settings are valid

Packaging Fails

Problem: Project packaging fails

Solutions:

1. Check packaging settings in Project Settings
2. Verify all required content is included
3. Check for missing dependencies
4. Review packaging logs for errors
5. See Build Packaging

Performance Issues

Low FPS

Problem: Frame rate below target (60-90 FPS)

Solutions:

1. Check performance targets: PERFORMANCE_TARGETS.md
2. Profile with Unreal Insights
3. Optimize assets (LODs, textures)
4. Adjust quality settings
5. See Performance Optimization

High Memory Usage

Problem: High RAM/VRAM usage

Solutions:

1. Check memory usage: Unreal Insights
2. Optimize texture sizes
3. Use texture streaming
4. Reduce LOD distances
5. Check for memory leaks

Getting Help

If you can't resolve an issue:

1. Check Documentation:

   • Documentation Index
   • FAQ
   • Relevant system/workflow docs

2. Review Logs:

   • Script logs: logs/ directory
   • Unreal Engine logs: Saved/Logs/
   • System logs

3. Search Issues:

   • Check if issue is already reported
   • Search project documentation
   • Search Unreal Engine forums

4. Report Issue:

   • Follow Bug Tracking Guide
   • Include error messages
   • Include system information
   • Include steps to reproduce

---

Last Updated: 2024