Maaz Zindani

Loading the index…

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

Elasticsearch and Kibana will not start with Docker Compose

Errormax virtual memory areas vm.max_map_count [X] is too low, increase to at least [Y]

Short answer

Elasticsearch in Docker usually fails for three documented reasons: the host kernel's vm.max_map_count is too low, Docker has less than the 4GB of memory the Compose guide asks for, or the passwords in .env break the rules (6+ alphanumeric characters). Read the Elasticsearch container log first.

  • Applies to Elasticsearch 9.x and 8.x images, Docker Compose v2, Ubuntu 24.04, Docker Desktop with WSL 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the Elasticsearch container log. A failed bootstrap check is printed there with the exact value.

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

    1. 1max virtual memory areas vm.max_map_count [X] is too low, increase to at least [Y]vm.max_map_count is too low on the Docker hostFix
    2. 2The same vm.max_map_count message although Linux host settings look rightDocker Desktop on Windows with WSL 2 needs the setting inside docker-desktopFix
    3. 3Your .env passwords contain characters such as ! or @, or are shorter than 6 charactersPasswords in .env break the stack's rulesFix
    4. 4Docker Desktop is set to less than 4GB of memoryDocker has too little memoryFix

What does the error look like?

  • max virtual memory areas vm.max_map_count [X] is too low, increase to at least [Y]
  • Elasticsearch 8 and Kibana do not start with Docker Compose

Cause 1 of 4

vm.max_map_count is too low on the Docker host

1Check

The bootstrap check needs at least 262144 memory-mapped areas on Linux, and Elastic recommends 1048576. In production mode a failed check stops startup.

sysctl vm.max_map_count

2Fix

Raise the value on the live system, and put it in /etc/sysctl.conf so it survives a reboot.

sudo sysctl -w vm.max_map_count=1048576
echo "vm.max_map_count = 1048576" | sudo tee -a /etc/sysctl.conf

3Verify

Restart the stack and watch the log reach a started state.

docker compose up -d
docker compose logs --tail 20

Confirmed by elastic.co

Did this fix it?

Cause 2 of 4

Docker Desktop on Windows with WSL 2 needs the setting inside docker-desktop

1Check

With the Docker Desktop WSL 2 backend the kernel setting lives in the docker-desktop distribution, not in your Ubuntu distro.

wsl -d docker-desktop -u root sysctl vm.max_map_count

2Fix

On Windows 11, Elastic documents editing sysctl.conf inside the docker-desktop distribution and adding the line shown. (For Windows 10 before 22H2 it documents a kernelCommandLine entry in .wslconfig instead.)

wsl -d docker-desktop -u root
vi /etc/sysctl.conf
# append this line:
vm.max_map_count = 1048576

3Verify

After wsl --shutdown and restarting Docker Desktop, the value is applied.

wsl --shutdown
wsl -d docker-desktop -u root sysctl vm.max_map_count

Confirmed by elastic.co

Did this fix it?

Cause 3 of 4

Passwords in .env break the stack's rules

1Check

The Compose guide says passwords must be at least 6 characters, alphanumeric, with no special characters such as ! or @, because the bash script in docker-compose.yml only works with alphanumeric passwords.

grep -E 'PASSWORD|STACK_VERSION' .env

2Fix

Use letters and digits only, at least 6 long, for ELASTIC_PASSWORD and KIBANA_PASSWORD. Remove the old volumes so the new passwords are applied from scratch.

docker compose down -v
docker compose up -d

3Verify

Open http://localhost:5601 and sign in as elastic with ELASTIC_PASSWORD.

curl -I http://localhost:5601

Confirmed by elastic.co

Did this fix it?

Cause 4 of 4

Docker has too little memory

1Check

The Compose guide asks you to allocate at least 4GB of memory to Docker Desktop.

docker info --format '{{.MemTotal}}'

2Fix

Raise the memory limit in Docker Desktop (or in .wslconfig for the WSL 2 backend) to 4GB or more.

# Docker Desktop: Settings > Resources > Memory = 4GB or more

3Verify

docker info shows at least 4 GB and the stack stays up.

docker compose ps

Confirmed by elastic.co

Did this fix it?

How do I stop it coming back?

  • Set vm.max_map_count in /etc/sysctl.conf on every Docker host that runs Elasticsearch.
  • Keep passwords alphanumeric and at least 6 characters in the stack's .env.
  • Pin STACK_VERSION in .env instead of floating on latest.
  • Give Docker Desktop at least 4GB before starting the stack.

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.