xgress3

Appearance

Troubleshooting ​

Use X-Xg3-Request-Id on every gateway response to correlate client failures with console diagnostics.

Request Lookup ​

  1. Copy X-Xg3-Request-Id from the client response headers (or from error JSON).
  2. In the console, open Request Lookup.
  3. Paste the ID and search.

The detail view shows authorization outcome, service, agent, timing, and optional captured backend response data when logging is enabled for the service. See Request logging for what is stored and what is never captured (including auth headers).

Share the request ID with your team or support when reporting issues.

Common ingress errors ​

SymptomLikely causeWhat to do
Agent unavailable (504-style)Agent tunnel down or agent disabledCheck agent detail — tunnel connected; agent enabled; agent process running
Policy deny / 401-styleWrong or missing auth headerMatch service auth mode; use X-Xg3-Authorization or X-Xg3-Service-Key, not both
Invalid credential at token endpointWrong client secret or scopeVerify account: and service: in scope match your account and service ID
Service not allowlistedCredential or key missing service IDUpdate allowed services on the credential or key
Backend 502 from agentBackend unreachable or agent overloadedVerify backend URL from agent host; check agent logs; review concurrency
Internal backend denied (InternalBackendAccessDenied)Private backend URL; agent Allow internal backend targets offEnable setting on agent or use public URL — Deny codes
Trial expired (TrialExpired)14-day trial ended without subscriptionBilling → Subscribe
Cannot enable agent or ServicePast due, trial expired, or cancelled subscriptionCheck Billing page status; update payment or subscribe
Rate limited (429)Too many requests to serviceBack off client; review traffic patterns

Gateway errors often use:

  • Content-Type: application/vnd.xg3.error+json
  • X-Xg3-Status header with a machine-readable status

Enrollment issues ​

SymptomWhat to do
Code rejectedUse the latest code from agent output; approve before expiry
Agent never connects after approvalOutbound HTTPS to gateway blocked; check firewall and XG3_GATEWAY / region
Wrong accountAgent approved into a different account than expected — verify account selector during approval
Region mismatchAgent --region must match console region selector
Unsure whether enrollment finishedOpen Event Viewer (or View Events on the agent) and look for enrollment approved / completed, or tunnel connected

See Agent enrollment and Event Viewer.

Service configuration ​

CheckDetail
Service enabledDisabled services reject ingress
Backend URLMust be absolute http:// or https://; reachable from agent host
HostnameClients must use https://{account}--{service}.{region}.xg3.io/...
Auth modeService must allow the mechanism your client uses

Test backend connectivity from the agent host (not your laptop) with curl or similar.

Agent logs ​

Logs are written to {data-dir}/logs/ on the agent host (service default: C:\ProgramData\xgress3\xg3agent\logs). See Install and run — Log files for rotation and retention.

Increase verbosity:

powershell
$env:RUST_LOG = "info"          # default if unset
$env:RUST_LOG = "xg3_agent=debug"   # tunnel / enrollment detail
xg3agent --region au

Windows services: set RUST_LOG in the service environment. The interactive console UI (Windows CLI without --no-interactive) keeps the screen clear — read logs/agent-YYYY-MM-DD.log for diagnostics.

If the agent runs as a service, attach to the log files rather than expecting console output. Enrollment codes appear as warnings in the log (and stderr when attached).

Exit code 2 (stand down) ​

If the agent exits with code 2, do not restart it in a loop. This indicates a renewal policy limit. Contact your xgress3 support channel.

See Agent operations.

IAM and missing menu items ​

If you cannot see Enroll Agent, Add Service, Event Viewer, or other actions, your role may not include that capability. Ask an account Admin or Account Manager to adjust your role under Settings → IAM.