# Troubleshooting Guide

Common issues and solutions for UE5 + Perforce + GitHub Actions builds.

## Perforce Issues

### "Perforce client error: Connect to server failed"

**Cause:** Cannot reach Perforce server or incorrect server address.

**Solutions:**
1. Verify P4PORT is correct: `p4 set P4PORT`
2. Check firewall allows port 1666 (or your custom port)
3. Test connection: `p4 -p ssl:your-server.com:1666 info`
4. Ensure SSL certificate is trusted if using SSL

### "Password invalid or unset"

**Cause:** Password not configured or expired.

**Solutions:**
1. Set password: `p4 set P4PASSWD=your_password`
2. Login manually: `p4 login`
3. For GitHub Actions, verify P4_PASSWORD secret is set correctly

### "Client 'ue5_build_workspace' unknown"

**Cause:** Workspace doesn't exist on server.

**Solutions:**
1. Create workspace: `p4 client ue5_build_workspace`
2. Verify workspace name matches P4CLIENT setting
3. Run setup script: `.\scripts\setup-build-machine.ps1`

### Sync is very slow

**Cause:** Large files, network latency, or initial sync.

**Solutions:**
1. Use parallel sync: `p4 sync -p`
2. Consider Perforce Proxy for remote offices
3. Exclude unnecessary files in workspace View
4. Use incremental builds instead of clean builds

## Unreal Engine Build Issues

### "Cannot find UnrealBuildTool"

**Cause:** UE5 not installed or incorrect path.

**Solutions:**
1. Verify UE5_ENGINE_PATH in workflow/config
2. Default path: `C:\Program Files\Epic Games\UE_5.4`
3. Check UBT exists: `Test-Path "$UE5Path\Engine\Binaries\DotNET\UnrealBuildTool.exe"`

### "Build failed with exit code 1"

**Cause:** Compilation errors in project code.

**Solutions:**
1. Check build logs in `D:\Builds\Logs`
2. Verify project builds locally in UE5 Editor
3. Sync to a known-good changelist
4. Check Visual Studio version compatibility

### "Out of memory during build"

**Cause:** Insufficient RAM or too many parallel build processes.

**Solutions:**
1. Close other applications
2. Increase VM size (Azure) or RAM
3. Reduce parallel builds: Edit BuildConfiguration.xml
4. Add `-MaxParallelActions=4` to UAT command

### "Cook failed for platform Win64"

**Cause:** Missing content, corrupt assets, or plugin issues.

**Solutions:**
1. Verify all content files are synced
2. Check for broken asset references in logs
3. Disable problematic plugins temporarily
4. Clear Derived Data Cache: Delete `Saved/DerivedDataCache`

### Build takes too long (>2 hours)

**Causes:** Clean builds, slow machine, or large project.

**Solutions:**
1. Use incremental builds (disable clean_build)
2. Enable IncrediBuild or FASTBuild if available
3. Upgrade to faster hardware (more cores, faster SSD)
4. Split into separate cook and package steps
5. Use distributed build system

## GitHub Actions Issues

### "Runner is offline"

**Cause:** Self-hosted runner not running or disconnected.

**Solutions:**
1. Check runner service: `Get-Service actions.runner.*`
2. Restart service: `Restart-Service actions.runner.*`
3. Check runner logs: `C:\actions-runner\_diag`
4. Re-register runner if needed

### "Permission denied" errors

**Cause:** Runner service account lacks permissions.

**Solutions:**
1. Run runner as Administrator
2. Grant permissions to build directories
3. Check Perforce user has read access
4. Verify Windows Defender isn't blocking

### Workflow never starts

**Cause:** No matching runner with required labels.

**Solutions:**
1. Verify runner has labels: `windows`, `ue5`, `perforce`
2. Check runner is online in GitHub repository settings
3. Review workflow `runs-on` requirements

### Artifacts fail to upload

**Cause:** Large build size or network issues.

**Solutions:**
1. Compress artifacts before upload
2. Split into multiple artifacts
3. Consider Azure Blob Storage instead
4. Check artifact size limits (10GB per artifact)

## Azure VM Issues

### VM provisioning fails

**Cause:** Quota limits or invalid configuration.

**Solutions:**
1. Check Azure subscription quotas
2. Try different VM size or region
3. Verify AZURE_CREDENTIALS secret is valid
4. Check Azure service principal permissions

### VM is too slow

**Cause:** Under-provisioned VM size.

**Solutions:**
1. Use larger VM size (Standard_D16s_v5 or higher)
2. Use Premium SSD storage
3. Enable accelerated networking
4. Consider dedicated host for consistent performance

### Build image not found

**Cause:** Custom UE5 image doesn't exist or wrong ID.

**Solutions:**
1. Create VM image with UE5 pre-installed
2. Verify AZURE_UE5_IMAGE_ID in secrets
3. Use marketplace Windows Server image and install UE5 in workflow (slow)

## Performance Optimization

### Slow Perforce Sync

- Use `p4 sync -p` for parallel sync
- Configure Perforce Proxy
- Exclude unnecessary files (binaries, intermediate files)

### Slow UE5 Compilation

- Use multiple cores: `-MaxParallelActions=16`
- Enable IncrediBuild or FASTBuild
- Use SSD storage (NVMe recommended)
- Disable Windows Defender for build directories

### Slow Cooking

- Enable iterative cooking: `-iterativecooking`
- Use multiple cores: `-CookMultiprocess`
- Cook only changed content
- Exclude debug content in Shipping builds

## Getting Help

If you can't resolve the issue:

1. Check GitHub Actions workflow logs
2. Review local logs:
   - Build logs: `D:\Builds\Logs`
   - Runner logs: `C:\actions-runner\_diag`
   - UE5 logs: `Saved\Logs`
3. Verify all prerequisites are installed (README.md)
4. Test build manually on build machine
5. Create GitHub issue with:
   - Error message
   - Workflow run link
   - Build machine specs
   - Relevant log excerpts

## Useful Commands

```powershell
# Check Perforce connection
p4 info

# Test Perforce login
p4 login -s

# View workspace configuration
p4 client -o ue5_build_workspace

# Check runner status
Get-Service actions.runner.*

# View runner logs
Get-Content C:\actions-runner\_diag\Runner_*.log -Tail 50

# Test UE5 installation
Test-Path "C:\Program Files\Epic Games\UE_5.4\Engine\Build\BatchFiles\RunUAT.bat"

# Check disk space
Get-PSDrive C

# View recent builds
Get-ChildItem D:\Builds | Sort-Object CreationTime -Descending | Select-Object -First 10
```