Introduction

Troubleshooting a legacy ASP.NET Core API inside a Linux container is easiest when you separate application problems from container problems. With .NET Core 2.1, that distinction matters even more because the runtime reached end of support on August 21, 2021, so many failures now involve old images, outdated dependencies, or assumptions that no longer match current hosting environments.

Start With the Simplest Signals

The first step is to confirm whether the container is failing to start, starting and crashing, or starting successfully but not serving requests.

docker ps -a
docker logs <container-name>
docker inspect <container-name>

Those three commands usually answer the first diagnostic questions:

• did the process exit immediately
• which port is exposed
• what environment variables reached the container
• what command actually started the application

If docker ps -a shows repeated restarts, focus on startup exceptions. If the container stays up but the API is unreachable, focus on port binding and networking.

Verify That Kestrel Listens on the Right Interface

A common mistake is binding Kestrel to localhost inside the container. That works from inside the container but not from the host or another container.

Set the API to listen on all interfaces.

docker run -p 8080:8080 \
  -e ASPNETCORE_URLS=http://0.0.0.0:8080 \
  myapi:latest

You can also hard-code this in Program.cs for older projects if necessary.

1using Microsoft.AspNetCore;
2using Microsoft.AspNetCore.Hosting;
3
4public class Program
5{
6    public static void Main(string[] args)
7    {
8        BuildWebHost(args).Run();
9    }
10
11    public static IWebHost BuildWebHost(string[] args) =>
12        WebHost.CreateDefaultBuilder(args)
13            .UseUrls("http://0.0.0.0:8080")
14            .UseStartup<Startup>()
15            .Build();
16}

If the app only listens on http://localhost:5000, port publishing on the Docker side will not rescue it.

Check the Dockerfile and Base Image

Legacy .NET images often fail because the runtime image does not match the published output. A minimal multi-stage Dockerfile for .NET Core 2.1 looks like this:

1FROM mcr.microsoft.com/dotnet/core/sdk:2.1 AS build
2WORKDIR /src
3COPY . .
4RUN dotnet restore
5RUN dotnet publish -c Release -o /app
6
7FROM mcr.microsoft.com/dotnet/core/aspnet:2.1
8WORKDIR /app
9COPY --from=build /app .
10ENTRYPOINT ["dotnet", "MyApi.dll"]

Make sure the final stage is an ASP.NET runtime image, not just the SDK by accident, and confirm that MyApi.dll matches the actual assembly name produced by publish.

Inside the container, check the runtime directly if needed:

docker exec -it <container-name> sh
dotnet --info
ls -la /app

Confirm Port Mapping and Health Checks

The next failure mode is a healthy app hidden behind a bad container mapping. Verify both the internal port and the published host port.

docker port <container-name>
curl http://localhost:8080/health

If the container is part of Docker Compose or a larger network, test from another container as well. Linux firewall rules are rarely the first issue in local Docker troubleshooting, but incorrect port declarations are extremely common.

Also inspect any health check configuration. A failing health check can cause orchestrators or scripts to restart a container that otherwise works.

Look for Environment and File-System Assumptions

A .NET Core API that works on Windows may fail on Linux because the environment is stricter. Pay attention to:

• case-sensitive file paths
• missing certificates or native libraries
• environment variables not passed into the container
• relative paths that assume a different working directory

For example, Config/appsettings.json and config/appsettings.json are different paths on Linux. Bugs like that often appear only after containerization.

If the API talks to a database or another service, test name resolution and connectivity from inside the container before assuming the API code is broken.

Common Pitfalls

The most common issue is binding to localhost instead of 0.0.0.0, which makes the API unreachable outside the container.

Another common problem is relying on a legacy 2.1 runtime image without realizing the stack is long out of support. Even if the container works, you should treat upgrade planning as part of the fix, not as a separate future task.

Developers also often debug only the Dockerfile and ignore Linux-specific path and environment differences. A working Windows build does not prove a Linux container is correctly configured.

Finally, avoid changing several variables at once. Confirm the process starts, then confirm the port binding, then confirm downstream dependencies. That sequence isolates the fault much faster.

Summary

• First determine whether the container crashes, runs but does not listen, or listens but is unreachable.
• Bind ASP.NET Core to 0.0.0.0, not localhost, inside Linux containers.
• Verify the Dockerfile, runtime image, published assembly name, and container port mapping.
• Check Linux-specific issues such as case-sensitive paths, missing environment variables, and dependency connectivity.
• Treat any .NET Core 2.1 troubleshooting as legacy support work and plan an upgrade alongside the immediate fix.