Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

A FastAPI container runs, but the browser gets no response on the mapped port

ErrorThe page never loads at http://localhost:8000, no error in the browser or in docker logs

Short answer

The container is up, but the request never reaches the app. Either the server listens on 127.0.0.1 inside the container, where the published port cannot reach it, or the -p mapping points at a port the app does not use. Bind to 0.0.0.0 and map the app's real port.

  • Applies to FastAPI CLI, Uvicorn, Docker Engine, Python 3.12
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the start-up line in the container log. It prints the address and port the server listens on.

    docker ps
    docker logs my-container --tail 20
  2. 2Match what you see, then jump to its fix

    1. 1The log says the app runs on http://127.0.0.1:8000The server listens on 127.0.0.1 inside the containerFix
    2. 2docker ps shows 0.0.0.0:8000->80/tcp while the app listens on 8000, or the other way roundThe published port does not match the port the app usesFix

What does the error look like?

  • The page never loads at http://localhost:8000, no error in the browser or in docker logs
  • The app works with fastapi dev on the host but not in the container

Cause 1 of 2

The server listens on 127.0.0.1 inside the container

1Check

fastapi dev, and Uvicorn by default, listen on 127.0.0.1, which is the machine talking to itself. Inside a container that means only the container. fastapi run listens on 0.0.0.0.

grep -n -E 'CMD|ENTRYPOINT' Dockerfile

2Fix

Start the server with fastapi run, or give Uvicorn the address 0.0.0.0. Use the exec form for CMD.

CMD ["fastapi", "run", "app/main.py", "--port", "8000"]
# or with Uvicorn
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

3Verify

Rebuild and request the app from the host.

docker build -t my-app .
docker run -d -p 8000:8000 my-app
curl -i http://localhost:8000/

Confirmed by fastapi.tiangolo.com

Did this fix it?

Cause 2 of 2

The published port does not match the port the app uses

1Check

-p takes HOST_PORT:CONTAINER_PORT. The container side must be the port in your CMD (the FastAPI Docker example sets --port 80 and runs the container with -p 80:80).

docker port my-container
docker logs my-container --tail 5

2Fix

Make the container side of -p the same as the --port in the command, and open the host side in the browser.

docker run -d --name my-container -p 8000:8000 my-app

3Verify

The host port answers.

curl -i http://localhost:8000/

Confirmed by fastapi.tiangolo.com

Did this fix it?

How do I stop it coming back?

  • Use fastapi run, not fastapi dev, as the container command.
  • Keep the app port in one place (an ARG or an environment variable) and use it for both --port and -p.
  • Check docker logs for the listening address on the first run of any new image.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.