/
Reference/
Troubleshooting runbook

Troubleshooting runbook

Use Debugging runbook for step-by-step diagnosis with GG_DEBUG.

Gateway

SymptomCauseSolution
Gateway won't startPort in use or permission deniedUse --port 8888 --httpPort 8889; check firewall
No modules in VisionWrong cwd or auto-detect failed--modules ./Explicit.dll --runtime netcore
CLR module fails on netcore GGRuntime mismatchUse --runtime clr or --runtime netcore to match DLL
Java module failsNot a JARPackage as JAR; set JAVA_HOME
Python/Ruby deps missingHost env incompleteInstall dependencies in GG host environment
Registration failedInterface changed, same versionBump version or use --noVersioning (dev)

Graft install

SymptomCauseSolution
404 from registryWrong registry URLCheck __graftcode vs __free; Vision install command
npm install failsWrong registry URL or package nameCopy install command from Vision; check __graftcode vs __free
Stale types in IDEOld Graft packageReinstall/update from registry

Runtime calls

SymptomCauseSolution
Connection failedWrong host/port/protocolTransport guide
Method not found--types filter or stale GraftCheck Vision; reinstall Graft
Type errorsInterface driftError handling
CORS error in browserMissing CORS configPorts and CORS
Stateful calls fail under LBNo stickinessStateless vs stateful
Auth rejectedToken not passed / invalidEdge client auth

Quick commands

# Enable protocol debug
GG_DEBUG=1 ./gg ./MyLib.dll --port 8888 --httpPort 8889

# Check Vision
curl -I http://localhost:8889/vision

# Check registry name
curl http://localhost:8889/registry

See also

PreviousGraft connection stringNextHow Graftcode works under the hood