Maaz Zindani

Loading the index…

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

A dev container port does not open in the browser when Docker runs on a remote host

ErrorThe port shows in the Forwarded Ports list but the page never loads

Short answer

Three things usually break it: the app listens only on localhost inside the container, so published ports are rejected; you open the container port instead of the mapped localhost port VS Code shows; or you changed appPort or a Compose ports list and did not rebuild. Check each in that order.

  • Applies to VS Code with Dev Containers extension, Remote - SSH, Docker Engine 27, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Inside the dev container terminal, see which address the app listens on. 127.0.0.1 means published ports cannot reach it; 0.0.0.0 or [::] means they can.

    ss -ltn
  2. 2Match what you see, then jump to its fix

    1. 1ss shows 127.0.0.1:3000 (not 0.0.0.0:3000) and a published port gets no answerThe app only listens on localhost inside the containerFix
    2. 2VS Code reports a different local port than the one in your app, for example 3000 mapped to 4123You are using the container port, not the mapped localhost portFix
    3. 3appPort or the Compose ports list shows the new value in the file, but the old mapping is still activeA published port was changed but the container was not rebuiltFix

What does the error look like?

  • The port shows in the Forwarded Ports list but the page never loads
  • If your application only accepts calls from localhost, it will reject connections from published ports
  • Port 3000 in the container opens on a different localhost port such as 4123

Cause 1 of 3

The app only listens on localhost inside the container

1Check

The Dev Containers docs say a published port acts like a network connection, so an app that only accepts calls from localhost rejects it. Forwarded ports appear to the app as localhost, so forwarding still works.

ss -ltn | grep 3000

2Fix

Either bind the app to all interfaces, or use forwardPorts instead of publishing. Add it to devcontainer.json, then reload the window.

// .devcontainer/devcontainer.json
{
  "forwardPorts": [3000]
}

3Verify

Open the localhost address VS Code lists for the port.

curl -I http://localhost:3000

Confirmed by code.visualstudio.com

Did this fix it?

Cause 2 of 3

You are using the container port, not the mapped localhost port

1Check

VS Code shows the localhost port to use in a notification and in the Forwarded Ports section of the Remote Explorer. It can differ from the container port.

# VS Code: open the Remote Explorer and read Forwarded Ports

2Fix

Open the address shown there, not the port number from the app's own log.

# example only: container port 3000 mapped to local 4123
curl -I http://localhost:4123

3Verify

The response comes from your app.

curl -I http://localhost:4123

Confirmed by code.visualstudio.com

Did this fix it?

Cause 3 of 3

A published port was changed but the container was not rebuilt

1Check

The docs list appPort in devcontainer.json and a ports list in docker-compose.yml as the two ways to publish a port, and tell you to rebuild afterwards.

docker ps --format '{{.Names}}  {{.Ports}}'

2Fix

Run Dev Containers: Rebuild Container from the Command Palette. For forwarded ports, reload or reopen the window after editing forwardPorts.

// devcontainer.json
"appPort": [ 3000, "8921:5000" ]

3Verify

The docker ps output now lists the new mapping.

docker ps --format '{{.Names}}  {{.Ports}}'

Confirmed by code.visualstudio.com

Did this fix it?

How do I stop it coming back?

  • Prefer forwardPorts for development, and publish a port only when another machine must reach it.
  • Run Docker on the SSH host and connect with Remote - SSH, then reopen in the container, so the setup matches the documented one.
  • Write the port numbers in devcontainer.json and not only in a manual Forward a Port action, so they survive a rebuild.

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.