Troubleshooting

Troubleshooting

Common issues and solutions for Unity Remote Server.

Server Not Starting

Issue: "Remote Server is not responding"

Symptoms:

• Cannot connect to http://127.0.0.1:8787
• No response from health endpoint

Solutions:

1. Check Unity Console for errors: Look for any error messages in the Unity Console window.

2. Verify package installation:

   • Open Package Manager (Window > Package Manager)
   • Check if "Unity Remote Server" is listed
   • If not, add via git URL: https://github.com/dsgarage/UnityRemoteServer.git

3. Check port availability:

   # macOS/Linux
   lsof -i :8787
   
   # Windows
   netstat -ano | findstr :8787

   If port is in use, either:

   • Stop the conflicting process
   • Or change the port in configuration

4. Restart Unity Editor: Sometimes a fresh restart resolves initialization issues.

Issue: "Port 8787 is already in use"

Solutions:

1. Find and kill the process:

   # macOS/Linux
   lsof -i :8787
   kill -9 <PID>
   
   # Windows
   netstat -ano | findstr :8787
   taskkill /PID <PID> /F

2. Change the port:

   // In an Editor script
   [InitializeOnLoad]
   public static class ChangeServerPort
   {
       static ChangeServerPort()
       {
           DSGarage.UnityRemoteServer.RemoteServer.Port = 8788;
       }
   }

Connection Issues

Issue: "Connection refused"

Possible causes:

• Unity Editor not running
• Remote Server package not installed
• Firewall blocking connection

Solutions:

1. Ensure Unity is running: The server only runs when Unity Editor is open.

2. Check firewall settings: Allow Unity Editor through firewall for local connections.

3. Test with curl:

   curl -v http://127.0.0.1:8787/health

Issue: "Timeout waiting for response"

Solutions:

1. Increase timeout values:

   curl -X POST http://127.0.0.1:8787/awaitCompile \
     -H "Content-Type: application/json" \
     -d '{"timeoutSec": 300}'

2. Check Unity's responsiveness:

   • Is Unity Editor frozen?
   • Are there infinite loops in your code?
   • Check CPU usage

Compilation Issues

Issue: "Compilation never completes"

Solutions:

1. Check for compilation errors:

   curl http://127.0.0.1:8787/errors?level=error

2. Clear Unity's cache:

   • Close Unity
   • Delete Library/ScriptAssemblies folder
   • Reopen Unity

3. Force reimport:

   curl -X POST http://127.0.0.1:8787/refresh \
     -H "Content-Type: application/json" \
     -d '{"force": true}'

Issue: "Build fails with no error message"

Solutions:

1. Check Unity Console: Build errors might only appear in Unity Console.

2. Verify build settings:

   • Open Build Settings in Unity
   • Ensure scenes are added
   • Check platform is properly configured

3. Check disk space: Ensure sufficient disk space for build output.

API Issues

Issue: "Invalid JSON response"

Example error:

SyntaxError: Unexpected token < in JSON at position 0

Solutions:

1. Check response content:

   curl -v http://127.0.0.1:8787/endpoint

2. Verify Content-Type header:

   curl -X POST http://127.0.0.1:8787/endpoint \
     -H "Content-Type: application/json" \
     -d '{}'

Issue: "404 Not Found"

Solutions:

1. Check endpoint path: Ensure you're using the correct endpoint path.

2. List available endpoints:

   // In Unity Console
   var endpoints = DSGarage.UnityRemoteServer.RemoteServer.GetEndpoints();
   foreach (var endpoint in endpoints)
   {
       Debug.Log(endpoint);
   }

Performance Issues

Issue: "Server responds slowly"

Solutions:

1. Check Unity's performance:

   • Open Profiler (Window > Analysis > Profiler)
   • Look for performance bottlenecks

2. Reduce log verbosity:

   DSGarage.UnityRemoteServer.RemoteServer.EnableDebugLogging = false;

3. Limit log entries:

   DSGarage.UnityRemoteServer.LogStore.MaxEntries = 100;

Issue: "Memory usage keeps increasing"

Solutions:

1. Clear logs periodically:

   curl -X POST http://127.0.0.1:8787/errors/clear

2. Reduce log buffer:

   LogStore.MaxEntries = 200; // Reduce from default

Script Errors

Issue: "jq: command not found"

Solutions:

1. Install jq:

   # macOS
   brew install jq
   
   # Ubuntu/Debian
   sudo apt-get install jq
   
   # Windows (via Chocolatey)
   choco install jq

2. Use Python script instead: Python scripts don't require jq.

Issue: "Permission denied" when running scripts

Solutions:

1. Make scripts executable:

   chmod +x Scripts/*.sh

2. Run with bash explicitly:

   bash Scripts/unity-build.sh android output.apk

Platform-Specific Issues

macOS Issues

Issue: "Unity is damaged and can't be opened"

Solution:

xattr -cr /Applications/Unity/Hub/Editor/2022.3.10f1/Unity.app

Issue: "Operation not permitted"

Solution: Grant Unity full disk access in System Preferences > Security & Privacy.

Windows Issues

Issue: "Windows Defender blocks Unity"

Solution: Add Unity installation folder to Windows Defender exclusions.

Issue: "Long path issues"

Solution: Enable long path support:

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

Linux Issues

Issue: "No display found"

Solution for headless systems:

xvfb-run -a Unity -batchmode -projectPath .

Debug Mode

Enable debug logging for troubleshooting:

// In Unity Editor script
[InitializeOnLoad]
public static class EnableDebugMode
{
    static EnableDebugMode()
    {
        DSGarage.UnityRemoteServer.RemoteServer.EnableDebugLogging = true;
        Debug.Log("Remote Server debug mode enabled");
    }
}

Getting Help

If you're still experiencing issues:

1. Check Unity Console for error messages
2. Review server logs:

   curl http://127.0.0.1:8787/errors?level=all

3. Enable debug mode (see above)
4. Create an issue on GitHub

When reporting issues, include:

• Unity version
• Operating system
• Error messages
• Steps to reproduce
• Relevant code snippets

Common Error Messages

Error	Cause	Solution
"ECONNREFUSED"	Server not running	Start Unity Editor
"ETIMEDOUT"	Server not responding	Check Unity is not frozen
"EADDRINUSE"	Port already in use	Change port or kill process
"401 Unauthorized"	Authentication required	Add API key to request
"500 Internal Server Error"	Server error	Check Unity Console for details
"Compilation in progress"	Unity is compiling	Wait or increase timeout

FAQ

Q: Can I run multiple Unity instances with Remote Server? A: Yes, but each needs a different port number.

Q: Does Remote Server work with Unity Cloud Build? A: No, it requires a local Unity Editor instance.

Q: Can I access Remote Server from another machine? A: By default no (security). You can modify binding address but it's not recommended.

Q: Why do some endpoints return HTML instead of JSON? A: This usually means the endpoint doesn't exist (404 page). Check the endpoint path.