Maaz Zindani

Loading the index…

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

OpenSearch Dashboards does not open at localhost:5601 after docker compose up

Errormax virtual memory areas vm.max_map_count [65530] is too low

Short answer

Start with docker compose ps and the logs: the cause is almost always in the OpenSearch node, not in Dashboards. Since 2.12 the stack needs OPENSEARCH_INITIAL_ADMIN_PASSWORD, the host needs vm.max_map_count at 262144, and a changed password does not apply to existing volumes.

  • Applies to OpenSearch 2.19, OpenSearch Dashboards 2.19, Docker Compose 2.40, Ubuntu 24.04, WSL 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See which containers are up, then read the logs of the OpenSearch node. Dashboards cannot start usefully until the node answers.

    docker compose ps
    docker compose logs
  2. 2Match what you see, then jump to its fix

    1. 1max virtual memory areas vm.max_map_count [65530] is too low in the OpenSearch log, and the node container stopsvm.max_map_count on the host is too lowFix
    2. 2The OpenSearch container is not running after docker compose up and no admin password is setThe admin password was never set, or is too weakFix
    3. 3Authentication finally failed for admin (HTTP 401) although .env holds the new passwordLogin fails with 401 after you changed the passwordFix
    4. 4local node does not have quorum in voting configurationA single-node edit was made while old two-node volumes remainFix

What does the error look like?

  • max virtual memory areas vm.max_map_count [65530] is too low
  • Authentication finally failed for admin
  • http://localhost:5601 does not load after docker compose up -d

Cause 1 of 4

vm.max_map_count on the host is too low

1Check

This is a setting of the host kernel, not of the container, so it must be raised on the machine running Docker. With Docker Desktop on Windows and WSL, that machine is the docker-desktop WSL distro.

cat /proc/sys/vm/max_map_count

2Fix

Set it to 262144 and make it permanent on Linux. On Windows with Docker Desktop, run the sysctl inside the docker-desktop distro.

# Linux: add to /etc/sysctl.conf, then apply
echo 'vm.max_map_count=262144' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Windows (PowerShell), Docker Desktop with WSL
wsl -d docker-desktop
sysctl -w vm.max_map_count=262144

3Verify

The value is 262144, then bring the stack up again.

cat /proc/sys/vm/max_map_count
docker compose up -d

Confirmed by docs.opensearch.org

Did this fix it?

Cause 2 of 4

The admin password was never set, or is too weak

1Check

From OpenSearch 2.12 you must provide OPENSEARCH_INITIAL_ADMIN_PASSWORD, either exported or in a .env file next to docker-compose.yml. The password must meet length, character-class and entropy requirements.

ls -a | grep -E '^\.env$'
docker compose config | grep OPENSEARCH_INITIAL_ADMIN_PASSWORD

2Fix

Create a .env file with a strong password. If it contains a dollar sign, put it in single quotes, because Compose reads $ followed by text as a variable.

# .env
OPENSEARCH_INITIAL_ADMIN_PASSWORD='use-a-long-unique-password-here'

3Verify

Start the stack and test the node over HTTPS with the demo certificate skipped (-k).

docker compose up -d
curl https://localhost:9200 -ku admin:'use-a-long-unique-password-here'

Confirmed by docs.opensearch.org

Did this fix it?

Cause 3 of 4

Login fails with 401 after you changed the password

1Check

OPENSEARCH_INITIAL_ADMIN_PASSWORD is used only on the first start, when the data volumes are empty. Changing it later and restarting does not change the stored password.

docker volume ls | grep -i opensearch

2Fix

Change the password with OpenSearch's documented password-change procedure, or, if the data is disposable, remove the volumes and start again. The second option deletes all data in them.

docker compose down -v
docker compose up -d

3Verify

The curl call with the password from .env now succeeds.

curl https://localhost:9200 -ku admin:'use-a-long-unique-password-here'

Confirmed by docs.opensearch.org

Did this fix it?

Cause 4 of 4

A single-node edit was made while old two-node volumes remain

1Check

You changed the two-node sample to discovery.type=single-node but kept the volumes, which still hold the cluster state of two nodes.

docker compose logs | grep -i quorum

2Fix

Remove the volumes and start again. This deletes the data in them.

docker compose down -v
docker compose up -d

3Verify

The node answers over HTTPS and Dashboards opens at http://localhost:5601.

curl https://localhost:9200 -ku admin:'use-a-long-unique-password-here'

Confirmed by docs.opensearch.org

Did this fix it?

How do I stop it coming back?

  • Keep OPENSEARCH_INITIAL_ADMIN_PASSWORD in a .env file that is not committed.
  • Document the vm.max_map_count setting next to the compose file, including the WSL command.
  • Do not change discovery settings on a stack that already has data volumes.
  • Use single quotes for passwords in .env and in curl commands.

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

Servers

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

If your application only accepts calls from localhost, it will reject connections from published ports

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.

3 causes, each with a fix

Next step

Want this handled for good?

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