Skip to main content

Troubleshooting

Common issues and resolutions for gateway administrators.

Service Startup Failures​

Container failed startup probe​

Symptom: Cloud Run revision fails with "container failed the configured startup probe checks"

Common causes:

  • Missing environment variable (check Terraform cloud-run/variables.tf)
  • Database connection failure (Spanner instance down or wrong config)
  • Spring bean wiring issue (missing scanBasePackages entry)

Debug:

  1. Check Cloud Run logs: gcloud logging read 'resource.labels.service_name="gateway-<service>-<env>"' --project=pinpoint-gateway --limit=20
  2. Look for APPLICATION FAILED TO START in the logs
  3. The "Description" section will tell you exactly which bean is missing

HikariPool connection timeout​

Symptom: Service hangs on startup, eventually fails with HikariPool timeout

Fix: Verify the Spanner instance is running and the PGAdapter config is correct. Check DATABASE_NAME and DATABASE_URL env vars.

Transaction Processing​

TransIT credential validation fails​

Symptom: INVALID_CREDENTIALS response when testing processor connection

Fix:

  1. Verify Device ID, Transaction Key match the TransIT boarding letter
  2. Ensure the merchant is boarded in the correct TransIT environment (test vs production)
  3. Check that the Developer ID matches the gateway's registered ID

Transaction stuck in PENDING​

Symptom: Transaction shows PENDING status and never resolves

Fix:

  1. Check the processing service logs for TransIT response errors
  2. Verify network connectivity to TransIT endpoints
  3. If TransIT is down, the transaction will auto-resolve when connectivity returns

Authentication​

Firebase token validation fails​

Symptom: 401 Unauthorized on all API calls

Fix:

  1. Verify FIREBASE_PROJECT_ID matches in both Terraform and Firebase console
  2. Check that the tenant ID is correct for the environment
  3. Ensure the Firebase Auth service account has the right permissions

SAML SSO loop​

Symptom: User gets redirected back to login after SAML authentication

Fix:

  1. Verify the SAML provider ACS URL matches the portal domain
  2. Check that the SAML provider is enabled in the Firebase tenant
  3. Ensure the user's email domain is in the allowed domains list

Monitoring​

Checking service health​

# Production
curl https://api.peakgateway.co/auth/health
curl https://api.peakgateway.co/management/health

# Staging
curl https://staging-api.peakgateway.co/auth/health

Viewing structured logs​

Logs are in ECS JSON format. Use Cloud Logging with filters:

resource.type="cloud_run_revision"
resource.labels.service_name="gateway-management-production"
jsonPayload.log.level="ERROR"