Troubleshooting Authentication and OTEL Issues in Self-Hosted Deployments

When deploying Formance in a self-hosted environment, you may encounter authentication or telemetry-related issues. Here's how to diagnose and resolve common problems.

Authentication Setup

Authentication for self-hosted deployments uses a hybrid approach:

• Portal authentication is handled by the Formance control plane

• Stack authentication uses OAuth2 delegation for local authentication without cloud dependency

Common Issues and Solutions

404 Errors on Authentication Endpoints

If you receive 404 errors when trying to access authentication endpoints (e.g., /.well-known/openid-configuration), verify that:

• All pods in your deployment are in "Running" state

• The auth service is properly configured and running

• Your ingress configuration is correctly routing authentication requests

OTEL Collector Issues

If you see connection errors related to port 4317 (OTEL gRPC), check that:

• The OpenTelemetry collector is running in your cluster

• The collector service is accessible from your application pods

• No network policies are blocking the connection to the OTEL collector

Prerequisites

Before deploying, ensure you have:

• PostgreSQL 13+ (PostgreSQL 14+ recommended)

• Properly configured database permissions

• Network access between all required services

Next Steps

If you continue experiencing issues after checking these points, examine the logs of the following components:

• Authentication service pods

• OTEL collector pods

• Ingress controller logs