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.

Spring Bean Wiring Issues​

These failures typically show up as APPLICATION FAILED TO START with a missing bean or an instantiation error.

NotificationPublisher: "No default constructor found"​

Symptom: Failed to instantiate [com.myriad.gateway.notifications.NotificationPublisher]: No default constructor found

Root cause: Kotlin compiles constructor default parameters into a synthetic secondary constructor. Without kotlin-reflect on the classpath, Spring can't use KotlinDetector.findPrimaryConstructor() to identify the primary constructor. Seeing multiple constructors and no @Autowired, Spring falls back to no-arg instantiation and fails.

Fix:

  • Ensure //tools/kotlin:kotlin_reflect is in the dep chain (libs/notifications/BUILD.bazel already includes it).
  • If creating a new library with @Component classes that have default constructor params, add kotlin-reflect.

Prevention: Always include kotlin-reflect when using Spring @Component with Kotlin default parameter values.

Missing ObjectMapper bean​

Symptom: required a bean of type 'com.fasterxml.jackson.databind.ObjectMapper' that could not be found

Root cause: In the Bazel build, Spring Boot auto-configuration doesn't provide ObjectMapper. Each service needs an explicit JacksonConfig class.

Fix:

  1. Add config/JacksonConfig.kt to the service.
  2. Copy an existing implementation from another service (for example, processing).

Minimal shape:

@Configuration(proxyBeanMethods = false)
class JacksonConfig {
  @Bean
  fun objectMapper(): ObjectMapper = ObjectMapper()
}

Prevention: When creating a new service, always include JacksonConfig.

Missing component scan package​

Symptom: Bean not found for a class in a shared library (for example, NotificationPublisher, FirebaseAuthService)

Root cause: The service's Application.kt doesn't include the library's package in scanBasePackages.

Fix: Add the library's package to the @SpringBootApplication(scanBasePackages = [...]) array.

Required packages:

  • com.myriad.gateway.shared (security)
  • com.myriad.gateway.notifications (if using notifications)

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"