You map ports like this:

ports:
  - "8080:8080"

or

ports:
  - "3457:3456"

and think you're done. Host port on the left, container port on the right. Simple, right?

A team I was helping had a Shopify app running in Docker for local development. Web service and a Postgres container. Postgres came up fine. The web container didn't. Every time it exited before it even finished starting with this error:

Port 3456 is not available for serving GraphiQL.

docker ps -a showed exit code 1. The logs just repeated the same line. No stack trace. No obvious typo. Just that.

The thing everyone tries first

So I did what most of us would do. Saw the word "port" in the error and just swapped it for a random number. Port not available? Change it. Sometimes that works. It's not the best approach and it's not guaranteed. Here it didn't work at all.

Why? Because we never looked at what the actual issue was. We just saw "port" and changed something. Guessing with extra steps.

So next we took the slower route, the one that actually gets you to the answer: reading the logs and the errors properly.

Read the logs and exit code first

Two commands, in order:

docker ps -a

Exit code 1. The process died on purpose, not from something like an OOM kill.

docker logs shopify-app-dev

Same line again: Port 3456 is not available for serving GraphiQL.

Now the compose file (web service only):

ports:
  - "3000:3000"
  - "3457:3456"

Here's the one thing you need to understand about Docker port mapping: host:container is a forwarding rule, not two copies of the same number. "3457:3456" means whatever hits 3457 on your machine gets sent to port 3456 inside the container. Docker sets that up whether or not anything is actually listening on 3456. The forwarding doesn't check.

It's like a postman walking up to your house and trying to deliver a message at the gate. If nobody is sitting at that gate, the message never gets through. The postman doesn't care. He just drops it and leaves.

We analyzed the files and logs, but they can be empty or stale. So we checked what Docker itself thinks is mapped:

docker inspect shopify-app-dev --format '{{json .NetworkSettings.Ports}}'

Same numbers came back: 3457 to 3456. Mapping is fine. It's just pointed at nothing.

We tried everything else and finally went to the docs. That's where it was: the Shopify CLI binds GraphiQL to port 5000 inside the container. Always. Not configurable from compose. Not something you'd guess.

What was actually wrong

The forwarding rule was correct. Every request to 3457 was routed to 3456 with no errors. Nothing was listening on 3456. The Shopify CLI had been bound to 5000 the whole time and the compose file was never updated to match.

The fix

# before
ports:
  - "3000:3000"
  - "3457:3456"

# after
ports:
  - "3000:3000"
  - "3457:5000"

docker-compose down
docker-compose up --build

GraphiQL comes up at http://localhost:3457.

The takeaway

host:container is just a forwarding rule. Docker does not care if anything is listening on the other side.

Next time a container dies with a port error, leave the host number alone at first. Check docker logs, then docker inspect, then find out what port the process inside the container is actually using. That is usually the entire bug.

Based on a real thread from the Shopify developer community.

FAQ

What's the difference between host port and container port in Docker? Host port is what you connect to from your machine. Container port is what the app inside is actually listening on. Docker forwards between them and has no opinion on whether the numbers match, as long as the container-side number matches where the app really binds.

Why does my container exit immediately after starting? Something inside is crashing on launch, often over a config or port mismatch. Check docker ps -a for the exit code, then docker logs <container>, before you change anything.

What port does the Shopify CLI use for GraphiQL? Port 5000 inside the container, by default, not configurable via compose.

How do I check what a container actually has mapped, not just what the YAML says?

docker inspect <container> --format '{{json .NetworkSettings.Ports}}'

I write these up as I hit them — full version and a few others like it at blogs.clouddojo.in.