Skip to content
Rack Gateway

Troubleshooting

This guide covers common issues with Rack Gateway and how to diagnose and resolve them.

Quick Diagnostics

Section titled “Quick Diagnostics”
Terminal window
# Check gateway health
curl https://gateway.example.com/api/v1/health


# View recent logs (Convox)
convox logs -a rack-gateway --since 10m

Authentication Issues

Section titled “Authentication Issues”

”Login Failed” After OAuth

Section titled “”Login Failed” After OAuth”

Possible causes:

  • GOOGLE_ALLOWED_DOMAIN doesn’t match the user’s email domain
  • Redirect URI mismatch in Google Cloud Console
  • DOMAIN misconfigured (affects OAuth redirects)

Checks:

  1. Confirm redirect URIs include:
    • https://<DOMAIN>/api/v1/auth/web/callback
    • https://<DOMAIN>/api/v1/auth/cli/callback
  2. Verify GOOGLE_ALLOWED_DOMAIN matches your workspace domain.

”Session Expired” Immediately

Section titled “”Session Expired” Immediately”

Possible causes:

  • APP_SECRET_KEY changed between restarts
  • Session timeout set too low

Checks:

  • Ensure APP_SECRET_KEY is stable and stored in Convox env.
  • Adjust timeout with RGW_SETTING_SESSION_TIMEOUT_MINUTES if needed.

CLI Login Hangs

Section titled “CLI Login Hangs”

The CLI does not run a local callback server. It opens the browser and polls the gateway.

  1. Check gateway reachability

    Terminal window
    curl https://gateway.example.com/api/v1/health

  2. Use --no-open to capture the auth URL

    Terminal window
    rack-gateway login production https://gateway.example.com --no-open

  3. Complete the browser flow

    Ensure the browser can reach the gateway and Google OAuth endpoints.

Authorization Issues

Section titled “Authorization Issues”

”Forbidden” for Expected Users

Section titled “”Forbidden” for Expected Users”

Possible causes:

  • User role not updated in the gateway
  • Permission requires MFA step-up

Checks:

  • Verify roles in the web UI (Users page).
  • If MFA is required, rerun the command and supply --mfa-code when prompted.

API Token Rejected

Section titled “API Token Rejected”

Possible causes:

  • Token revoked or expired
  • Token not passed correctly

Checks:

  • Token must start with rgw_.
  • Use RACK_GATEWAY_API_TOKEN or --api-token.
  • Confirm token exists in the web UI (API Tokens).

Convox Proxy Issues

Section titled “Convox Proxy Issues”

”Bad Gateway” Errors

Section titled “”Bad Gateway” Errors”

Possible causes:

  • Convox API unreachable
  • RACK_TOKEN invalid or missing
  • RACK_HOST misconfigured

Checks:

  • Verify RACK_TOKEN is correct and set.
  • If running outside the rack network, set RACK_HOST to the Convox API URL.
  • Check gateway logs for upstream errors.

MFA Issues

Section titled “MFA Issues”

”Invalid TOTP Code”

Section titled “”Invalid TOTP Code””
  • Ensure device clock is in sync
  • Try the next code window (30 seconds)

“WebAuthn Not Available”

Section titled ““WebAuthn Not Available””
  • Ensure the CLI build has WebAuthn support (CGO + libfido2)
  • Fall back to TOTP when needed

Lost MFA Device

Section titled “Lost MFA Device”
  1. Use backup codes if available
  2. Ask an admin to remove MFA methods in the web UI

Database Issues

Section titled “Database Issues”

If the gateway fails to start or reports DB errors:

  1. Verify DATABASE_URL / RGW_DATABASE_URL is set
  2. Run migrations:
Terminal window
convox run admin -- ./rack-gateway-api migrate -a rack-gateway