Skip to contents

Troubleshooting

troubleshooting.Rmd

Troubleshooting

Most setup problems come from Docker not running, the image not being downloaded yet, or port 3838 already being used by another container.

Docker Desktop Is Not Running

Open Docker Desktop and wait for the status indicator to show that Docker is running. This can take a minute or two.

On Windows, Docker may ask to finish WSL 2 setup or restart the computer. Complete those prompts before trying to run MicroHub.

MicroHub Image Cannot Be Found

In Docker Desktop, go to the Images tab and search for cdcgov/microhub.

If you do not see it:

  1. Check that you typed the name exactly as cdcgov/microhub.
  2. Make sure the Images search is looking at remote images, not only local images already on your computer.
  3. Search again and select the v2.0.0 tag.
  4. Click Pull and wait for the download to finish.

If a facilitator asks you to use the command line instead, open PowerShell on Windows or Terminal on macOS/Linux and run:

docker pull cdcgov/microhub:v2.0.0

After the pull finishes, return to Docker Desktop and check the Images tab.

Port 3838 Is Already in Use

This means another app or container is already using the same browser address that MicroHub wants to use.

In Docker Desktop, go to the Containers tab and stop any other running MicroHub or Shiny containers. Then start MicroHub again with host port 3838 and container port 3838.

If a different host port is required, use that number in the browser URL. For example, host port 3839 means opening http://localhost:3839.

The Browser Says the App Cannot Be Reached

  1. Confirm the MicroHub container is running in Docker Desktop.
  2. Confirm the host and container ports are both set to 3838.
  3. Open http://localhost:3838, not a public website URL.
  4. If the container stopped, open its logs in Docker Desktop and share the first visible error with a facilitator.

If the page still does not open, stop the microhub container in Docker Desktop, start it again, and refresh the browser page.

Docker Desktop Asks You to Sign In

A Docker account is not required for the workshop. If Docker Desktop shows a sign-in screen, look for an option to continue without signing in, skip sign-in, or use Docker Desktop without an account.

CSV Upload Fails

Check that the file has exactly the required columns and no extra header rows above the column names.

Required column Example
date 2026-05-16 or 5/16/26
target_group Overall
value 42

A Model Run Is Slow

Some models take longer than the baselines, especially on laptops with limited memory or CPU. During workshop exercises, start with baseline models and Copycat before running heavier models. Close unused applications if the computer is under memory pressure.