Troubleshooting

Common issues and solutions when building or running GTProxy

Build Issues

CMake cannot find Conan

Problem: CMake configuration fails with an error about missing Conan.

Solution:

Ensure Conan 2.0+ is installed:

pip install "conan>2.0"

Verify the installation:

conan --version

If using a virtual environment, make sure it’s activated before running CMake.

Git submodules not found

Problem: Build fails with errors about missing files in lib/enet or lib/cpp-httplib.

Solution:

Initialize and update submodules:

git submodule update --init --recursive

If you cloned without --recurse-submodules, this will fetch the missing dependencies.

C++23 compiler errors

Problem: Build fails with errors about C++23 features not being available.

Solution:

Ensure you’re using a C++23-compatible compiler:

• Windows: Visual Studio 2022 or newer
• Linux: GCC 11+ or Clang 14+
• macOS: Xcode 14+ or Clang 14+

Update your compiler if necessary. On Linux, you can specify a compiler:

cmake -B build -DCMAKE_CXX_COMPILER=g++-12

Conan dependency resolution fails

Problem: Conan fails to find compatible package versions.

Solution:

Clear the Conan cache and retry:

conan cache clean "*" --build
conan cache clean "*" --source

If the issue persists, ensure your Conan profile is correctly configured:

conan profile detect --force

Remove the build directory and reconfigure:

rm -rf build
cmake -B build -DCMAKE_BUILD_TYPE=Release

LibreSSL build errors on Windows

Problem: LibreSSL fails to compile on Windows with MSVC.

Solution:

This is usually a transient issue with Conan package binaries. Try:

1. Update Conan:

   pip install --upgrade conan
   

2. Force a rebuild of LibreSSL:

   conan install . --build=libressl
   

3. If the issue persists, you may need to use a different SSL library. Edit conanfile.py to use OpenSSL instead:

   self.requires('openssl/3.2.0')
   

Link errors with eventpp or sol2

Problem: Linker fails to find symbols from header-only libraries.

Solution:

These libraries are header-only and should not cause link errors. If you see link errors:

1. Clean and rebuild:

   rm -rf build
   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   

2. Ensure you’re not mixing Debug and Release builds.

3. Check that the library is properly included in your CMakeLists.txt.

Runtime Issues

GTProxy crashes on startup

Problem: The proxy crashes immediately when launched.

Solution:

1. Check configuration: Ensure config.json exists and is valid JSON. If missing, GTProxy should create a default one.

2. Run with logging: Enable debug logging to see detailed error messages:

   # Edit config.json and set log level to "debug"
   ./build/src/GTProxy
   

3. Check dependencies: On Linux, verify all shared libraries are available:

   ldd ./build/src/GTProxy
   

4. Port conflicts: Ensure the proxy port (default 16999) is not already in use:

   # Linux/macOS
   netstat -tuln | grep 16999
   
   # Windows
   netstat -ano | findstr 16999
   

Cannot connect to Growtopia servers

Problem: GTProxy starts but cannot connect to Growtopia servers.

Solution:

1. Check internet connection: Ensure you have a stable internet connection.

2. Firewall rules: Make sure your firewall allows GTProxy to make outbound connections.

3. IP flagged: Some IP addresses may be flagged by Growtopia servers. Try:

   • Using a different network
   • Using a VPN (ensure the VPN allows UDP traffic)
   • Contacting your ISP if your residential IP is blocked

4. Server status: Check if Growtopia servers are online and accessible.

Lua scripts not loading

Problem: Scripts in the scripts/ directory are not being executed.

Solution:

1. Check script location: Ensure scripts are in the correct directory relative to the executable.

2. Syntax errors: Verify Lua syntax is correct:

   lua -c scripts/your_script.lua
   

3. Enable script logging: Check GTProxy logs for script loading errors.

4. File permissions: Ensure script files are readable:

   chmod +r scripts/*.lua
   

HTTP server not accessible

Problem: Cannot access the built-in HTTP server at http://localhost:port.

Solution:

1. Check configuration: Verify the HTTP server is enabled in config.json.

2. Port binding: Ensure the HTTP server port is not blocked by a firewall.

3. Listen address: Check if the server is listening on the correct interface (0.0.0.0 for all, 127.0.0.1 for localhost only).

4. Process verification: Confirm GTProxy is running:

   # Linux/macOS
   ps aux | grep GTProxy
   
   # Windows
   tasklist | findstr GTProxy
   

Packet modification not working

Problem: Modified packets are not being applied or are causing disconnections.

Solution:

1. Packet structure: Verify the packet structure matches the current Growtopia version.

2. Serialization: Ensure your packet serialization/deserialization is correct.

3. Packet size: Check that modified packets don’t exceed size limits.

4. Validation: Some packets have checksums or validation that must be updated after modification.

5. Debug mode: Enable packet logging to see raw packet data:

   {
     "log_level": "debug"
   }
   

Platform-Specific Issues

Windows

Missing DLL errors

Problem: Error about missing .dll files when running GTProxy.

Solution:

1. Visual C++ Redistributable: Install the Microsoft Visual C++ Redistributable:

   • Download from Microsoft

2. Conan DLLs: Ensure Conan dependencies are in the same directory as the executable or in PATH.

3. Copy DLLs manually: You may need to copy DLLs from the Conan cache to the build directory.

Windows Defender blocks execution

Problem: Windows Defender flags GTProxy as malware.

Solution:

This is a false positive common with network tools. Add an exclusion:

1. Open Windows Security
2. Go to “Virus & threat protection”
3. Click “Manage settings”
4. Under “Exclusions”, add the GTProxy directory

Note: Only do this if you built GTProxy yourself from trusted source code.

Linux

Permission denied when binding to ports

Problem: GTProxy fails to bind to ports below 1024.

Solution:

On Linux, ports below 1024 require root privileges. Either:

1. Use a higher port: Edit config.json to use a port above 1024 (recommended)

2. Grant capabilities:

   sudo setcap cap_net_bind_service=+ep ./build/src/GTProxy
   

3. Run as root: (not recommended)

   sudo ./build/src/GTProxy
   

Shared library errors

Problem: Error about missing shared libraries (.so files).

Solution:

Install missing dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libssl-dev zlib1g-dev

# Arch Linux
sudo pacman -S openssl zlib

# Fedora
sudo dnf install openssl-devel zlib-devel

Update library cache:

sudo ldconfig

macOS

Unsigned binary warning

Problem: macOS blocks GTProxy because it’s from an unidentified developer.

Solution:

1. Control-click the executable and select “Open”
2. Or, remove the quarantine flag:
   xattr -d com.apple.quarantine ./build/src/GTProxy
   

Note: Only do this for binaries you built yourself.

Homebrew vs system libraries conflict

Problem: Build uses wrong library versions from Homebrew.

Solution:

Ensure Conan is using the correct toolchain:

conan profile detect --force

If issues persist, specify the Xcode toolchain:

cmake -B build -DCMAKE_OSX_SYSROOT=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk

Testing Issues

Tests fail to compile

Problem: Test executable fails to build.

Solution:

Ensure Google Test is properly installed via Conan:

conan install . --build=gtest

Rebuild the project:

cmake --build build --target GTProxy_tests

Tests fail at runtime

Problem: Tests compile but fail when executed.

Solution:

1. Run specific test: Isolate the failing test:

   ./build/tests/GTProxy_tests --gtest_filter=TestSuite.TestName
   

2. Verbose output: Enable verbose output:

   ./build/tests/GTProxy_tests --gtest_verbose
   

3. Working directory: Some tests may depend on specific files being in the working directory. Run from the project root:

   cd /path/to/GTProxy
   ./build/tests/GTProxy_tests
   

Performance Issues

High CPU usage

Problem: GTProxy consumes excessive CPU resources.

Solution:

1. Build type: Ensure you’re using a Release build, not Debug:

   cmake -B build -DCMAKE_BUILD_TYPE=Release
   cmake --build build --config Release
   

2. Logging level: Reduce logging verbosity in config.json:

   {
     "log_level": "info"
   }
   

3. Script optimization: Review Lua scripts for inefficient loops or excessive logging.

High memory usage

Problem: GTProxy uses too much memory.

Solution:

1. Memory leaks: Run with a memory debugger:

   valgrind --leak-check=full ./build/src/GTProxy
   

2. Packet buffering: Reduce buffer sizes in network configuration.

3. Script cleanup: Ensure Lua scripts properly release resources.

Getting Help

If you encounter an issue not covered here:

1. Check logs: Review GTProxy logs for detailed error messages
2. GitHub Issues: Search existing issues at github.com/ZTzTopia/GTProxy/issues
3. Create an issue: If your problem is new, create a detailed issue report including:
   • Operating system and version
   • Compiler version
   • CMake and Conan versions
   • Full error messages and logs
   • Steps to reproduce

View on GitHub

Report issues or contribute to the project