Build failures

Opsflw Connect documentation builds fail most often because a required preflight step was skipped or a recent content change broke navigation. Use the checks below to quickly restore a green pipeline.

Confirm required tooling

Verify that the global Python and Node dependencies match the repository requirements. Install or upgrade them with the project-provided manifests.

pip install --user -r requirements.txt
npm install

If the install commands report missing permissions, ensure you are not running inside a restricted container or shell session. Retry after enabling the recommended user-level package directories.

Run the preflight suite locally

Execute the same commands that CI uses before opening a pull request. Address any failures before re-running the suite.

mkdocs build --strict
npx markdownlint-cli "docs/**/*.md"
npx playwright test

Resolve navigation warnings from mkdocs build by checking mkdocs.yml for incorrect paths or duplicate headings. Fix lint errors by wrapping long lines or adding the required blank lines around fenced code blocks.

Capture failing output for review

When the build still fails, copy the command output into your pull request or support ticket. Include the exact command, the error snippet, and any recent content changes. This context helps reviewers reproduce the issue quickly.