Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ZTzTopia/GTProxy/llms.txt

Use this file to discover all available pages before exploring further.

​
Build Issues

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.
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.
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
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
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')

​
Runtime Issues

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
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.
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
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
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

Problem: Error about missing .dll files when running GTProxy.Solution:
  1. Visual C++ Redistributable: Install the Microsoft Visual C++ Redistributable:
  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.
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

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
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

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.
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

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
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

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.
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

Build docs developers (and LLMs) love

Get started for freeTalk to us