Versioning Troubleshooting

🚀Versioning Troubleshooting

Version Recovery

Separate generation, conversion, file synchronization, local tag creation, and publication before correcting a release value.

Commandcusty version update

📦Category

Troubleshooting

🚀Quick Command

strategy -> generated value -> project file -> optional Git tag

---

strategiesformatsversion filetags

---

⚙️

Strategies

5

🐍

Default Version File

app/__version__.py

🏷️

Explicit Tag Shape

vX.Y.Z

🌿

Git Tag

Separate effect

Scope of This Page

Use this page to separate strategy generation, format conversion, file synchronization, Git tag creation, and publication across Custy. Use the Version or Tag command guide after the failing responsibility is known.

Identify the Failing Responsibility

ℹ️Information

Generation	Custy could not calculate a new value from strategy, repository history, bump, or release modifiers.
Conversion	The release tag and project ecosystem require different compatible representations.
Synchronization	The selected value exists, but the configured version file is missing, unwritable, or was not updated.
Tag creation	A local Git tag is missing, invalid, or conflicts with an existing reference.
Publication	The local version and tag are correct, but a remote push failed or only some destinations succeeded.

---

Version File Missing or Unchanged

• Confirm tool.custy.cli.paths.version_file points to an existing writable file in the intended project.
• Check for a command-line --version-file override.
• Run from the project root so relative paths resolve correctly.
• If dry-run was active, no file write is expected.
• Inspect the file and git diff rather than relying only on summary output.

---

Invalid Strategy or Unexpected Format

• Use semver, pep440, commitizen, date, or gitcount.
• Compare existing tags with the selected strategy; incompatible history can prevent latest-tag interpretation or produce an unexpected next value.
• Review prerelease, development, post-release, metadata, and epoch inputs.
• Basic SemVer and PEP 440 bridging does not cover every advanced form.
• Generated formats are broader than the shared explicit-tag validator.

⚠️Explicit tag input is currently narrow

Options using the shared validator normalize a missing v and accept only vX.Y.Z. A generated prerelease or PEP 440 value can be valid internally but still be rejected when supplied through that explicit CLI input.

---

Commitizen Failure

Confirm the external cz executable is installed, project Commitizen metadata is valid, and eligible Conventional Commits exist.

🛡️Current strategy delegation is not runnable as written

The active Commitizen strategy infers a bump but passes an unsupported keyword when constructing SemverStrategy. This requires an application fix; changing TOML cannot correct it.

---

Tag Conflict

Inspect before choosing recovery

bash

git show --decorate <tag>
git tag --points-at HEAD
git ls-remote --tags origin <tag>

If the expected tag already exists, verify its target and publication state. Choose another approved version or follow the team's coordinated tag-repair procedure. Do not move a published tag casually.

---

Safe Retry

1. Preserve the first error and current file/Git state.
2. Correct the version path, strategy, input, or repository history problem.
3. Preview the smallest applicable operation.
4. Inspect the version file and resolved tag.
5. Confirm whether a commit or tag already exists before running a larger release profile.

---

Continue

🚀Related Commands

Commands commonly used together with this command.

Version Troubleshooting

Resolve focused Version Update failures.

Tag Troubleshooting

Resolve validation, version input, and existing-tag conflicts.

Version Formats

Compare strategy values, common forms, conversions, and known limits.

Versioning Concept

Understand selection, preparation, synchronization, and Git tagging.