Understanding Azure Spring Apps Configuration and Service Registry

Azure Spring Apps (formerly Azure Spring Cloud) provided a managed platform for running Spring Boot microservices with built-in configuration management and service discovery. As of March 2025, Azure Spring Apps has been retired. Microsoft recommends migrating to Azure Container Apps or Azure Kubernetes Service for new and existing workloads. This guide covers the most common configuration and service registry errors you may encounter during migration or while maintaining existing deployments.

Important: Azure Spring Apps Enterprise and Basic/Standard tiers reached end-of-life in March 2025. Plan your migration to Azure Container Apps or AKS. See the official retirement announcement for details.

Diagnostic Context

When encountering Azure Spring Apps configuration and service registry, the first step is understanding what changed. In most production environments, errors do not appear spontaneously. They are triggered by a change in configuration, code, traffic patterns, or the platform itself. Review your deployment history, recent configuration changes, and Azure Service Health notifications to identify potential triggers.

Azure maintains detailed activity logs for every resource operation. These logs capture who made a change, what was changed, when it happened, and from which IP address. Cross-reference the timeline of your error reports with the activity log entries to establish a causal relationship. Often, the fix is simply reverting the most recent change that correlates with the error onset.

If no recent changes are apparent, consider external factors. Azure platform updates, regional capacity changes, and dependent service modifications can all affect your resources. Check the Azure Status page and your subscription’s Service Health blade for any ongoing incidents or planned maintenance that coincides with your issue timeline.

Common Pitfalls to Avoid

When fixing Azure service errors under pressure, engineers sometimes make the situation worse by applying changes too broadly or too quickly. Here are critical pitfalls to avoid during your remediation process.

First, avoid making multiple changes simultaneously. If you change the firewall rules, the connection string, and the service tier all at once, you cannot determine which change actually resolved the issue. Apply one change at a time, verify the result, and document what worked. This disciplined approach builds reliable operational knowledge for your team.

Second, do not disable security controls to bypass errors. Opening all firewall rules, granting overly broad RBAC permissions, or disabling SSL enforcement might eliminate the error message, but it creates security vulnerabilities that are far more dangerous than the original issue. Always find the targeted fix that resolves the error while maintaining your security posture.

Third, test your fix in a non-production environment first when possible. Azure resource configurations can be exported as ARM or Bicep templates and deployed to a test resource group for validation. This extra step takes minutes but can prevent a failed fix from escalating the production incident.

Fourth, document the error message exactly as it appears, including correlation IDs, timestamps, and request IDs. If you need to open a support case with Microsoft, this information dramatically speeds up the investigation. Azure support engineers can use correlation IDs to trace the exact request through Microsoft’s internal logging systems.

Service Registry (Eureka) Configuration Errors

Missing Eureka Client Dependency

The most common service registry error is failing to include the Eureka client library. Without it, your application cannot register with or discover services from the managed Eureka Server.

<!-- Maven: Add Eureka client dependency -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
</dependency>

<!-- Also include the Spring Cloud BOM -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>2023.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

// Gradle
implementation 'org.springframework.cloud:spring-cloud-starter-netflix-eureka-client'

Eureka Registration Failure

In Azure Spring Apps, the managed Eureka server URL is injected automatically. Do not hardcode Eureka server URLs in your application.yml. If you override the Eureka URL, registration will fail.

# WRONG — Do not hardcode Eureka URL in Azure Spring Apps
eureka:
  client:
    serviceUrl:
      defaultZone: http://localhost:8761/eureka/

# CORRECT — Let Azure Spring Apps inject the URL automatically
# Just ensure the dependency is present; no eureka config needed
spring:
  application:
    name: my-service

Service Discovery Not Working Between Apps

If services are registered but cannot discover each other:

• Verify all apps are deployed within the same Azure Spring Apps instance
• Check that spring.application.name is set correctly — this becomes the service ID
• Ensure apps use @EnableDiscoveryClient or @EnableEurekaClient annotation
• Allow time for registration — Eureka has a 30-second heartbeat interval by default

@SpringBootApplication
@EnableDiscoveryClient
public class MyServiceApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyServiceApplication.class, args);
    }
}

// Using RestTemplate with service discovery
@Bean
@LoadBalanced
public RestTemplate restTemplate() {
    return new RestTemplate();
}

// Call by service name instead of URL
String response = restTemplate.getForObject(
    "http://order-service/api/orders", String.class);

Config Server Issues

Embedded Config Server Conflicts

Azure Spring Apps provides a managed Config Server. If your application includes its own embedded Spring Cloud Config Server dependency, it conflicts with the managed one.

<!-- REMOVE this from your pom.xml —
     Azure Spring Apps provides Config Server -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-config-server</artifactId>
</dependency>

<!-- KEEP this — Config Client is correct -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-config</artifactId>
</dependency>

Config Server Git Repository Binding

# Configure Config Server to use a Git repository
az spring config-server git set \
  --name mySpringApp \
  --resource-group myRG \
  --uri https://github.com/myorg/config-repo \
  --label main \
  --search-paths config

# For private repos, add credentials
az spring config-server git set \
  --name mySpringApp \
  --resource-group myRG \
  --uri https://github.com/myorg/config-repo \
  --username myuser \
  --password mytoken

Config Refresh Not Working

If configuration changes in Git are not reflected in running applications:

# application.yml — enable config refresh
management:
  endpoints:
    web:
      exposure:
        include: refresh, health, info

spring:
  cloud:
    config:
      # Fail fast if Config Server is unreachable
      fail-fast: true
      retry:
        max-attempts: 6
        initial-interval: 1000

// Use @RefreshScope for beans that need dynamic config
@RefreshScope
@RestController
public class MyController {
    @Value("${app.feature-flag}")
    private boolean featureFlag;
}

JVM Memory Configuration Errors

Out of Memory in Small App Plans

Spring Boot applications are memory-intensive. The default JVM heap allocation may exceed the memory limit of your app instance size.

# Check current JVM options
az spring app show \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  --query "properties.temporaryDisk"

# Set JVM options with appropriate memory limits
az spring app update \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  --jvm-options="-Xms512m -Xmx1024m -XX:MaxMetaspaceSize=256m"

Instance Size	Memory	Recommended JVM Settings
0.5 vCPU, 1 GB	1 GB	-Xms256m -Xmx512m
1 vCPU, 2 GB	2 GB	-Xms512m -Xmx1024m
2 vCPU, 4 GB	4 GB	-Xms1g -Xmx2g

Root Cause Analysis Framework

After applying the immediate fix, invest time in a structured root cause analysis. The Five Whys technique is a simple but effective method: start with the error symptom and ask “why” five times to drill down from the surface-level cause to the fundamental issue.

For example, considering Azure Spring Apps configuration and service registry: Why did the service fail? Because the connection timed out. Why did the connection timeout? Because the DNS lookup returned a stale record. Why was the DNS record stale? Because the TTL was set to 24 hours during a migration and never reduced. Why was it not reduced? Because there was no checklist for post-migration cleanup. Why was there no checklist? Because the migration process was ad hoc rather than documented.

This analysis reveals that the root cause is not a technical configuration issue but a process gap that allowed undocumented changes. The preventive action is creating a migration checklist and review process, not just fixing the DNS TTL. Without this depth of analysis, the team will continue to encounter similar issues from different undocumented changes.

Categorize your root causes into buckets: configuration errors, capacity limits, code defects, external dependencies, and process gaps. Track the distribution over time. If most of your incidents fall into the configuration error bucket, invest in infrastructure-as-code validation and policy enforcement. If they fall into capacity limits, improve your monitoring and forecasting. This data-driven approach focuses your improvement efforts where they will have the most impact.

Deployment and JAR Errors

Invalid JAR Format

Azure Spring Apps requires an executable JAR built with the Spring Boot Maven or Gradle plugin:

<!-- Maven: Ensure the spring-boot-maven-plugin is present -->
<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

# Build executable JAR
mvn clean package -DskipTests

# Verify JAR is executable
java -jar target/myapp-0.0.1-SNAPSHOT.jar

# Deploy JAR to Azure Spring Apps
az spring app deploy \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  --artifact-path target/myapp-0.0.1-SNAPSHOT.jar

Source Code Deployment vs JAR

# Deploy from source (builds remotely)
az spring app deploy \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  --source-path ./

# Custom builder (Enterprise tier)
az spring app deploy \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  --source-path ./ \
  --build-env BP_JVM_VERSION=17

Diagnostic Logging

Checking Application Logs

# Stream real-time logs
az spring app logs \
  --name myApp \
  --service mySpringApp \
  --resource-group myRG \
  -f  # follow

# Query historical logs via Log Analytics
az monitor log-analytics query \
  --workspace myWorkspace \
  --analytics-query "AppPlatformLogsforSpring 
    | where AppName == 'myApp'
    | where Log contains 'ERROR'
    | project TimeGenerated, Log
    | order by TimeGenerated desc
    | take 50"

KQL Queries for Common Issues

// Find Eureka registration failures
AppPlatformLogsforSpring
| where Log contains "eureka" and Log contains "error"
| project TimeGenerated, AppName, InstanceName, Log
| order by TimeGenerated desc

// Find Config Server connection issues
AppPlatformLogsforSpring
| where Log contains "ConfigServicePropertySourceLocator" 
    or Log contains "config server"
| project TimeGenerated, AppName, Log
| order by TimeGenerated desc

// Find OutOfMemory errors
AppPlatformLogsforSpring
| where Log contains "OutOfMemoryError" or Log contains "heap space"
| project TimeGenerated, AppName, InstanceName, Log

Error Classification and Severity Assessment

Not all errors require the same response urgency. Classify errors into severity levels based on their impact on users and business operations. A severity 1 error causes complete service unavailability for all users. A severity 2 error degrades functionality for a subset of users. A severity 3 error causes intermittent issues that affect individual operations. A severity 4 error is a cosmetic or minor issue with a known workaround.

For Azure Spring Apps configuration and service registry, map the specific error codes and messages to these severity levels. Create a classification matrix that your on-call team can reference when triaging incoming alerts. This prevents over-escalation of minor issues and under-escalation of critical ones. Include the expected resolution time for each severity level and the communication protocol (who to notify, how frequently to update stakeholders).

Track your error rates over time using Azure Monitor metrics and Log Analytics queries. Establish baseline error rates for healthy operation so you can distinguish between normal background error levels and genuine incidents. A service that normally experiences 0.1 percent error rate might not need investigation when errors spike to 0.2 percent, but a jump to 5 percent warrants immediate attention. Without this baseline context, every alert becomes equally urgent, leading to alert fatigue.

Implement error budgets as part of your SLO framework. An error budget defines the maximum amount of unreliability your service can tolerate over a measurement window (typically monthly or quarterly). When the error budget is exhausted, the team shifts focus from feature development to reliability improvements. This mechanism creates a structured trade-off between innovation velocity and operational stability.

Dependency Management and Service Health

Azure services depend on other Azure services internally, and your application adds additional dependency chains on top. When diagnosing Azure Spring Apps configuration and service registry, map out the complete dependency tree including network dependencies (DNS, load balancers, firewalls), identity dependencies (Azure AD, managed identity endpoints), and data dependencies (storage accounts, databases, key vaults).

Check Azure Service Health for any ongoing incidents or planned maintenance affecting the services in your dependency tree. Azure Service Health provides personalized notifications specific to the services and regions you use. Subscribe to Service Health alerts so your team is notified proactively when Microsoft identifies an issue that might affect your workload.

For each critical dependency, implement a health check endpoint that verifies connectivity and basic functionality. Your application’s readiness probe should verify not just that the application process is running, but that it can successfully reach all of its dependencies. When a dependency health check fails, the application should stop accepting new requests and return a 503 status until the dependency recovers. This prevents requests from queuing up and timing out, which would waste resources and degrade the user experience.

Actuator and Health Checks

# Enable actuator endpoints for debugging
management:
  endpoints:
    web:
      exposure:
        include: health, info, env, configprops, beans
  endpoint:
    health:
      show-details: always
      probes:
        enabled: true

# Custom health check for downstream services
management:
  health:
    defaults:
      enabled: true

@Component
public class DatabaseHealthIndicator implements HealthIndicator {
    @Override
    public Health health() {
        try {
            // Check database connectivity
            jdbcTemplate.queryForObject("SELECT 1", Integer.class);
            return Health.up().withDetail("database", "reachable").build();
        } catch (Exception e) {
            return Health.down().withException(e).build();
        }
    }
}

Migration to Azure Container Apps

Since Azure Spring Apps is retired, here is a migration path to Azure Container Apps:

# 1. Create a Dockerfile for your Spring Boot app
cat <<'EOF' > Dockerfile
FROM mcr.microsoft.com/openjdk/jdk:17-ubuntu
WORKDIR /app
COPY target/*.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]
EOF

# 2. Build and push to ACR
az acr build --registry myACR --image myapp:latest .

# 3. Create Container App
az containerapp create \
  --name myapp \
  --resource-group myRG \
  --environment myEnvironment \
  --image myACR.azurecr.io/myapp:latest \
  --target-port 8080 \
  --ingress external \
  --min-replicas 1 \
  --max-replicas 5 \
  --cpu 1 --memory 2Gi

# 4. For service discovery, use Dapr or Container Apps built-in service discovery
az containerapp create \
  --name myapp \
  --resource-group myRG \
  --environment myEnvironment \
  --image myACR.azurecr.io/myapp:latest \
  --enable-dapr \
  --dapr-app-id myapp \
  --dapr-app-port 8080

Post-Resolution Validation and Hardening

After applying the fix, perform a structured validation to confirm the issue is fully resolved. Do not rely solely on the absence of error messages. Actively verify that the service is functioning correctly by running health checks, executing test transactions, and monitoring key metrics for at least 30 minutes after the change.

Validate from multiple perspectives. Check the Azure resource health status, run your application’s integration tests, verify that dependent services are receiving data correctly, and confirm that end users can complete their workflows. A fix that resolves the immediate error but breaks a downstream integration is not a complete resolution.

Implement defensive monitoring to detect if the issue recurs. Create an Azure Monitor alert rule that triggers on the specific error condition you just fixed. Set the alert to fire within minutes of recurrence so you can respond before the issue impacts users. Include the remediation steps in the alert’s action group notification so that any on-call engineer can apply the fix quickly.

Finally, conduct a brief post-incident review. Document the root cause, the fix applied, the time to detect, diagnose, and resolve the issue, and any preventive measures that should be implemented. Share this documentation with the broader engineering team through a blameless post-mortem process. This transparency transforms individual incidents into organizational learning that raises the entire team’s operational capability.

Consider adding the error scenario to your integration test suite. Automated tests that verify the service behaves correctly under the conditions that triggered the original error provide a safety net against regression. If a future change inadvertently reintroduces the problem, the test will catch it before it reaches production.

Summary

Azure Spring Apps configuration errors typically stem from missing Eureka client dependencies, hardcoded service URLs that conflict with managed infrastructure, embedded Config Server conflicts, and JVM memory misconfigurations. Since the service is now retired, the most important action is migrating to Azure Container Apps or AKS. For existing deployments still running, use Log Analytics with the AppPlatformLogsforSpring table and Spring Boot Actuator endpoints for diagnostics.

For more details, refer to the official documentation: What is Azure Spring Apps?, Deploy your first application to Azure Spring Apps, Analyze logs and metrics in Azure Spring Apps.