Mkdocs builds worked for past 2 months, now fails with: Command failed with exit code 127: mkdocs build

My site has been building and deploying just fine for the past two months. About 24 hours ago, my builds started to fail. I’m using mkdocs to build the site.

The build fails here:
1:46:39 PM: $ mkdocs build
1:46:39 PM: bash: mkdocs: command not found

mkdocs appears to have been installed. Before the “command not found” error, the logs say:

1:46:04 PM: Successfully installed click-8.1.7 ghp-import-2.1.0 importlib-metadata-8.5.0 jinja2-3.1.4 markdown-3.7 markupsafe-2.1.5 mergedeep-1.3.4 mkdocs-1.5.3 packaging-24.1 pathspec-0.12.1 platformdirs-4.3.6 python-dateutil-2.9.0.post0 pyyaml-6.0.2 pyyaml-env-tag-0.1 six-1.16.0 watchdog-4.0.2 zipp-3.20.2

  • Here is the full build log:
    1:45:54 PM: build-image version: e9374cfad82db8353c2f0accb0411d4d9451e459 (focal)
    1:45:54 PM: buildbot version: e9374cfad82db8353c2f0accb0411d4d9451e459
    1:45:54 PM: Building without cache
    1:45:54 PM: Starting to prepare the repo for build
    1:45:55 PM: No cached dependencies found. Cloning fresh repo
    1:45:55 PM: git clone --filter=blob:none redacted (Steven Tobin) · GitHub
    1:45:55 PM: Preparing Git Reference refs/heads/master
    1:45:59 PM: Starting to install dependencies
    1:45:59 PM: Attempting Python version ‘3.8’, read from environment
    1:45:59 PM: downloading cpython-3.8.20+20241002-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
    1:45:59 PM: installing cpython-3.8.20+20241002-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz
    1:46:00 PM: python --version
    1:46:00 PM: Python 3.8.20
    1:46:00 PM: mise python@3.8.20 ✓ installed
    1:46:00 PM: Python version set to 3.8
    1:46:00 PM: Installing pip dependencies from requirements.txt
    1:46:00 PM: Started restoring cached pip cache
    1:46:00 PM: Finished restoring cached pip cache
    1:46:02 PM: Collecting mkdocs==1.5.3 (from -r requirements.txt (line 1))
    1:46:02 PM: Downloading mkdocs-1.5.3-py3-none-any.whl.metadata (6.2 kB)
    1:46:02 PM: Collecting click>=7.0 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading click-8.1.7-py3-none-any.whl.metadata (3.0 kB)
    1:46:02 PM: Collecting ghp-import>=1.0 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading ghp_import-2.1.0-py3-none-any.whl.metadata (7.2 kB)
    1:46:02 PM: Collecting importlib-metadata>=4.3 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading importlib_metadata-8.5.0-py3-none-any.whl.metadata (4.8 kB)
    1:46:02 PM: Collecting jinja2>=2.11.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading jinja2-3.1.4-py3-none-any.whl.metadata (2.6 kB)
    1:46:02 PM: Collecting markdown>=3.2.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading Markdown-3.7-py3-none-any.whl.metadata (7.0 kB)
    1:46:02 PM: Collecting markupsafe>=2.0.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading MarkupSafe-2.1.5-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (3.0 kB)
    1:46:02 PM: Collecting mergedeep>=1.3.4 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading mergedeep-1.3.4-py3-none-any.whl.metadata (4.3 kB)
    1:46:02 PM: Collecting packaging>=20.5 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading packaging-24.1-py3-none-any.whl.metadata (3.2 kB)
    1:46:02 PM: Collecting pathspec>=0.11.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading pathspec-0.12.1-py3-none-any.whl.metadata (21 kB)
    1:46:02 PM: Collecting platformdirs>=2.2.0 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading platformdirs-4.3.6-py3-none-any.whl.metadata (11 kB)
    1:46:02 PM: Collecting pyyaml-env-tag>=0.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:02 PM: Downloading pyyaml_env_tag-0.1-py3-none-any.whl.metadata (4.1 kB)
    1:46:02 PM: Collecting pyyaml>=5.1 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:03 PM: Downloading PyYAML-6.0.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (2.1 kB)
    1:46:03 PM: Collecting watchdog>=2.0 (from mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:03 PM: Downloading watchdog-4.0.2-py3-none-manylinux2014_x86_64.whl.metadata (38 kB)
    1:46:03 PM: Collecting python-dateutil>=2.8.1 (from ghp-import>=1.0->mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:03 PM: Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl.metadata (8.4 kB)
    1:46:03 PM: Collecting zipp>=3.20 (from importlib-metadata>=4.3->mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:03 PM: Downloading zipp-3.20.2-py3-none-any.whl.metadata (3.7 kB)
    1:46:03 PM: Collecting six>=1.5 (from python-dateutil>=2.8.1->ghp-import>=1.0->mkdocs==1.5.3->-r requirements.txt (line 1))
    1:46:03 PM: Downloading six-1.16.0-py2.py3-none-any.whl.metadata (1.8 kB)
    1:46:03 PM: Downloading mkdocs-1.5.3-py3-none-any.whl (3.7 MB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 3.7/3.7 MB 49.4 MB/s eta 0:00:00
    1:46:03 PM: Downloading click-8.1.7-py3-none-any.whl (97 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 97.9/97.9 kB 16.7 MB/s eta 0:00:00
    1:46:03 PM: Downloading ghp_import-2.1.0-py3-none-any.whl (11 kB)
    1:46:03 PM: Downloading importlib_metadata-8.5.0-py3-none-any.whl (26 kB)
    1:46:03 PM: Downloading jinja2-3.1.4-py3-none-any.whl (133 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 133.3/133.3 kB 25.4 MB/s eta 0:00:00
    1:46:03 PM: Downloading Markdown-3.7-py3-none-any.whl (106 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 106.3/106.3 kB 22.4 MB/s eta 0:00:00
    1:46:03 PM: Downloading MarkupSafe-2.1.5-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (26 kB)
    1:46:03 PM: Downloading mergedeep-1.3.4-py3-none-any.whl (6.4 kB)
    1:46:03 PM: Downloading packaging-24.1-py3-none-any.whl (53 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 54.0/54.0 kB 9.2 MB/s eta 0:00:00
    1:46:03 PM: Downloading pathspec-0.12.1-py3-none-any.whl (31 kB)
    1:46:03 PM: Downloading platformdirs-4.3.6-py3-none-any.whl (18 kB)
    1:46:03 PM: Downloading PyYAML-6.0.2-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (746 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 746.5/746.5 kB 69.9 MB/s eta 0:00:00
    1:46:03 PM: Downloading pyyaml_env_tag-0.1-py3-none-any.whl (3.9 kB)
    1:46:03 PM: Downloading watchdog-4.0.2-py3-none-manylinux2014_x86_64.whl (82 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 82.9/82.9 kB 13.6 MB/s eta 0:00:00
    1:46:03 PM: Downloading python_dateutil-2.9.0.post0-py2.py3-none-any.whl (229 kB)
    1:46:03 PM: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 229.9/229.9 kB 37.1 MB/s eta 0:00:00
    1:46:03 PM: Downloading zipp-3.20.2-py3-none-any.whl (9.2 kB)
    1:46:03 PM: Downloading six-1.16.0-py2.py3-none-any.whl (11 kB)
    1:46:03 PM: Installing collected packages: zipp, watchdog, six, pyyaml, platformdirs, pathspec, packaging, mergedeep, markupsafe, click, pyyaml-env-tag, python-dateutil, jinja2, importlib-metadata, markdown, ghp-import, mkdocs
    1:46:04 PM: Successfully installed click-8.1.7 ghp-import-2.1.0 importlib-metadata-8.5.0 jinja2-3.1.4 markdown-3.7 markupsafe-2.1.5 mergedeep-1.3.4 mkdocs-1.5.3 packaging-24.1 pathspec-0.12.1 platformdirs-4.3.6 python-dateutil-2.9.0.post0 pyyaml-6.0.2 pyyaml-env-tag-0.1 six-1.16.0 watchdog-4.0.2 zipp-3.20.2
    1:46:04 PM: [notice] A new release of pip is available: 24.1.2 → 24.2
    1:46:04 PM: [notice] To update, run: pip install --upgrade pip
    1:46:04 PM: Pip dependencies installed
    1:46:05 PM: Attempting Ruby version 2.6.2, read from environment
    1:46:06 PM: Required ruby-2.6.2 is not installed - installing.
    1:46:06 PM: Searching for binary rubies, this might take some time.
    1:46:07 PM: Found remote file https://rubies.travis-ci.org/ubuntu/20.04/x86_64/ruby-2.6.2.tar.bz2
    1:46:07 PM: Checking requirements for ubuntu.
    1:46:08 PM: Requirements installation successful.
    1:46:08 PM: ruby-2.6.2 - #configure
    1:46:08 PM: ruby-2.6.2 - #download
    1:46:10 PM: No checksum for downloaded archive, recording checksum in user configuration.
    1:46:10 PM: ruby-2.6.2 - #validate archive
    1:46:15 PM: ruby-2.6.2 - #extract
    1:46:18 PM: ruby-2.6.2 - #validate binary
    1:46:18 PM: ruby-2.6.2 - #setup
    1:46:19 PM: ruby-2.6.2 - #gemset created /opt/buildhome/.rvm/gems/ruby-2.6.2@global
    1:46:19 PM: ruby-2.6.2 - #importing gemset /opt/buildhome/.rvm/gemsets/global.gems…
    1:46:19 PM: ruby-2.6.2 - #generating global wrappers…
    1:46:19 PM: ruby-2.6.2 - #gemset created /opt/buildhome/.rvm/gems/ruby-2.6.2
    1:46:19 PM: ruby-2.6.2 - #importing gemsetfile /opt/buildhome/.rvm/gemsets/default.gems evaluated to empty gem list
    1:46:20 PM: ruby-2.6.2 - #generating default wrappers…
    1:46:20 PM: Using /opt/buildhome/.rvm/gems/ruby-2.6.2
    1:46:21 PM: Using Ruby version 2.6.2
    1:46:22 PM: Started restoring cached go cache
    1:46:22 PM: Finished restoring cached go cache
    1:46:22 PM: Installing Go version 1.12 (requested 1.12)
    1:46:27 PM: go version go1.12 linux/amd64
    1:46:28 PM: Using PHP version 8.0
    1:46:31 PM: Downloading and installing node v20.18.0…
    1:46:31 PM: Downloading https://nodejs.org/dist/v20.18.0/node-v20.18.0-linux-x64.tar.xz
    1:46:31 PM: Computing checksum with sha256sum
    1:46:32 PM: Checksums matched!
    1:46:35 PM: Now using node v20.18.0 (npm v10.8.2)
    1:46:35 PM: Enabling Node.js Corepack
    1:46:35 PM: Started restoring cached build plugins
    1:46:35 PM: Finished restoring cached build plugins
    1:46:35 PM: Successfully installed dependencies
    1:46:36 PM: Starting build script
    1:46:37 PM: Detected 0 framework(s)
    1:46:37 PM: Section completed: initializing
    1:46:39 PM: ​
    1:46:39 PM: Netlify Build
    1:46:39 PM: ────────────────────────────────────────────────────────────────
    1:46:39 PM: ​
    1:46:39 PM: ❯ Version
    1:46:39 PM: @netlify/build 29.55.2
    1:46:39 PM: ​
    1:46:39 PM: ❯ Flags
    1:46:39 PM: accountId: 5d52d9d77redacted
    1:46:39 PM: baseRelDir: false
    1:46:39 PM: buildId: 67114d3c8bd1288def114d47
    1:46:39 PM: deployId: 67114d3c8bd1288def114d49
    1:46:39 PM: ​
    1:46:39 PM: ❯ Current directory
    1:46:39 PM: /opt/build/repo
    1:46:39 PM: ​
    1:46:39 PM: ❯ Config file
    1:46:39 PM: No config file was defined: using default values.
    1:46:39 PM: ​
    1:46:39 PM: ❯ Context
    1:46:39 PM: production
    1:46:39 PM: ​
    1:46:39 PM: Build command from Netlify app
    1:46:39 PM: ────────────────────────────────────────────────────────────────
    1:46:39 PM: ​
    1:46:39 PM: $ mkdocs build
    1:46:39 PM: bash: mkdocs: command not found
    1:46:39 PM: ​
    1:46:39 PM: “build.command” failed
    1:46:39 PM: ────────────────────────────────────────────────────────────────
    1:46:39 PM: ​
    1:46:39 PM: Error message
    1:46:39 PM: Command failed with exit code 127: mkdocs build (Search results for '"non-zero exit code: 127"' - Netlify Support Forums)
    1:46:39 PM: ​
    1:46:39 PM: Error location
    1:46:39 PM: In Build command from Netlify app:
    1:46:39 PM: mkdocs build
    1:46:39 PM: ​
    1:46:39 PM: Resolved config
    1:46:39 PM: build:
    1:46:39 PM: command: mkdocs build
    1:46:39 PM: commandOrigin: ui
    1:46:39 PM: publish: /opt/build/repo/site
    1:46:39 PM: publishOrigin: ui
    1:46:40 PM: Failed during stage ‘building site’: Build script returned non-zero exit code: 2 (Search results for '"non-zero exit code: 2"' - Netlify Support Forums)
    1:46:40 PM: Build failed due to a user error: Build script returned non-zero exit code: 2
    1:46:40 PM: Failing build: Failed to build site
    1:46:40 PM: Finished processing build request in 46.186s

I didn’t change anything in requirements.txt (it only has mkdocs==1.5.3) or any of the build settings. I tried performing “Clear cache and retry with latest branch commit”, but the build still failed.

Any help would be appreciated. I’m not sure what changed to break the builds.

I think this issue is related to the changes Netlify made mentioned in Project that's been stable for years has suddenly started failing "poetry: command not found"

I ran into the same issue for my mkdocs site, however I was able to use the workaround mentioned in the other thread because I’m using a netlify.toml /poetry for my build settings. Unfortunately I’m not sure how to remedy this in the UI build settings.

Tagging the Netlify folks who replied in the other thread for visibility: @serhalp @lukas.holzer

Hi @jimmarq @thisguise, thank you for reporting this!

We rolled back the changes to our build system about an hour ago. Could you try it again and let us know if it’s working now?

Thanks!

Yep, my previous build settings are working again now. Thanks!

Builds are working, now. Thanks!

awesome! thanks for writing back in and confirming your builds are working again.

@SamO My builds have stopped working again(!) Was something related to these changes reverted?

No! What does your build log say?

I posted a new thread including the error details there

Hi, our mkdocs builds started failing overnight as well: Netlify.

We have a very simple setup that should hopefully be trivial to reproduce on your end.

The ‘Initializing’ step manages to install Python dependencies using pipenv without issues. However, in the ‘Building’ step, neither the mkdocs, nor the pipenv commands are found in $PATH. Our build command used to be simply mkdocs build but I changed it to pipenv run mkdocs build in case something changed with venv activation on your end, but that didn’t solve the issue. It now complains about missing pipenv instead.

Thanks,

Hey @ti-mo, I’m sorry to hear that we broke something for you. Do you have any reproducible examples, maybe?

I have a test site that works perfectly fine:

Can you spot a difference to your site?

I’m using the following netlify.toml

command = "mkdocs build"
publish = "site/"
environment = { PYTHON_VERSION = "3.13" }

With those requirements.txt

mkdocs==1.6
mkdocs-material==9.5.41

Hi @lukas.holzer, thanks for trying.

As I mentioned in my previous post, we’re using pipenv, not requirements.txt.

netlify.toml:

[build]
  base = "docs/"
  publish = "site/"
  command = "mkdocs build"

Pipfile:

[[source]]
url = "https://pypi.org/simple"
verify_ssl = true
name = "pypi"

[packages]
mkdocs = "*"
pymdown-extensions = "*"
mkdocs-material = "*"
mkdocs-macros-plugin = "*"
mkdocs-git-revision-date-localized-plugin = "*"
mkdocs-git-authors-plugin = "*"

[dev-packages]

[requires]
# Whatever Netlify's Ubuntu version uses.
python_version = "3.8"

If you’re trying to reproduce, don’t forget to run pipenv lock to generate Pipfile.lock and commit it to the repo.


Unrelated, if I set environment = { PYTHON_VERSION = "3.13" } in netlify.toml, it doesn’t even manage to find Pipenv for that version:

12:32:54 PM: mise python@3.13.0 ✓ installed
12:32:54 PM: Python version set to 3.13
12:32:54 PM: Found Pipfile, restoring Pipenv virtualenv
12:32:54 PM: Started restoring cached python virtualenv
12:32:54 PM: Finished restoring cached python virtualenv
12:32:54 PM: Installing dependencies from Pipfile
12:32:54 PM: /opt/build-bin/run-build-functions.sh: line 524: /opt/buildhome/.mise/installs/python/3.13/bin/pipenv: No such file or directory

I assume users wanting to use pipenv with non-default Python versions need to install it explicitly.

Just as an FYI, my builds have been working consistently using mkdocs since the October 17 fix. I never changed the build settings in my post at the top of this thread.

Hi, any update on this? It seems like neither pipenv nor the Python tools installed during Initializing step are available in the Building step. Tried again today and still seems to be the case.

I can create a new thread for this if that makes things easier, please let me know.

They devs are checking this and we’ll let you know once we have an update. Currently we have a PR in review that might potentially fix this.

1 Like