FAQ & Troubleshooting

Common issues

No analysers run

Cause: All analysers are disabled or their optional dependencies are missing.

Fix: Enable the required analysers in Configuration Reference and install their dependencies using the instructions in Installation.

Configuration not found

Cause: bumpwright.toml is missing or located outside the current working directory.

Fix: Create the file or pass --config to specify its path. See Configuration Reference for details.

Git errors

Cause: Commands are executed outside a Git repository or references such as --base and --head are unreachable.

Fix: Run inside a valid repository and ensure the required references exist. Additional setup tips can be found in Installation.

Version keeps incrementing

Cause: The version file was modified by a previous run and has not been committed or reverted.

Fix: Commit or discard the change before rerunning, or use --dry-run to preview the bump without writing to disk. See usage for details on dry runs.

Changelog file not created

Cause: --changelog was supplied without a file path or the destination directory does not exist.

Fix: Pass a valid path to --changelog or create the containing directory before running Bumpwright.

Template path not found

Cause: The Jinja2 template used for release notes, referenced by --changelog-template, cannot be located.

Fix: Provide the full path to an existing Jinja2 template or add it to the expected location so Bumpwright can render the release notes.

FAQ

Why do I get version conflicts when bumping?

Conflicting version numbers in files or Git tags can cause bumps to fail. Ensure the version defined in your configuration matches the latest tag. See Configuration Reference for controlling version sources.

How do I check which analysers ran?

Run with --format json to inspect analyser impacts or review your configuration to see which analysers are enabled. The CLI Reference describes all available command-line options.

Can I simulate a bump without writing to disk?

Yes. Run with --dry-run to preview changes without modifying files. --dry-run still respects --changelog for path resolution but does not write any files. The usage guide explains how to combine this with other options.

Why do I see Git errors about missing references?

Bumpwright compares two Git references. Fetch all remote branches and tags so the specified --base and --head exist. See Installation for repository setup tips.