> ## Documentation Index
> Fetch the complete documentation index at: https://zerv.wisl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for common zerv errors - no reachable tags, VCS not found, unknown schemas, conflicting options, config parse errors, and PEP440 normalization confusion.

## No version tags are reachable from HEAD

```
Error: No version tags are reachable from HEAD
```

zerv versions builds relative to the latest reachable tag; a repo (or branch) without any
tag has no base version. Fixes:

* Create the first tag: `git tag v0.1.0 && git push origin v0.1.0`
* Seed the base version explicitly: `zerv flow --tag-version "v0.1.0"`
* In CI, check out with full history: a shallow clone (`fetch-depth: 1`) can cut the tags
  off. zerv's [reusable workflow](/cicd/github-actions) uses `fetch-depth: 0` for exactly
  this reason.

## VCS not found: git

```
Error: VCS not found: git
```

zerv could not find a Git repository at the working directory. Fixes:

* Run from inside the repository, or point at it: `zerv version -C /path/to/repo`
* Versioning something that is not a repo (a plain artifact, a manual value)? Skip VCS
  entirely: `zerv version --source none --tag-version 1.2.3 --distance 5`

## Running `zerv` shows help and exits

Running bare `zerv` prints the full help and exits with code `2`. zerv requires a
subcommand: `version`, `flow`, `check`, or `render`. For example:

```bash theme={null}
zerv version
```

## Unknown schema

```
Error: Unknown schema: standard-bse
```

Typo'd or unsupported `--schema` name. Preset names come from the built-in list; see
[schema system](/concepts/schema-system). For anything custom, write a RON schema instead:

```bash theme={null}
zerv version --schema-ron '(core:[var(Major), var(Minor), var(Patch)], extra_core:[], build:[])'
```

## Conflicting options

```
Error: Conflicting options: ...
```

Two flags that cannot combine. The common ones:

* `--output-prefix` with `--output-template`: put the prefix inside the template instead,
  `--output-template "v{{ major }}.{{ minor }}"`
* `--clean` with `--dirty`: pick one state

```bash theme={null}
zerv render "1.2.3" --output-template "v{{major}}" --output-prefix "v"
# Error: Conflicting options: Cannot use --output-template with --output-prefix. ...
```

## Config parse error

```
Error: Config parse error: ...
```

`zerv.toml` failed to parse. The file only accepts stable policy fields: an ephemeral
per-build flag (`dirty = true`, `bump_minor = true`, `major = 2`) or a typo'd key is
rejected loudly at parse time (`deny_unknown_fields`) rather than silently ignored. Remove
the key or move it to the matching section (`[version]` / `[flow]`). See the
[config file](/concepts/config-file) page for the allowed fields.

## PEP440 output looks different from SemVer output

Not an error. The same version renders differently per format, by design:

```
semver: 1.0.0-alpha.2.post.5.dev.3+build.1
pep440: 1.0.0a2.post5.dev3+build.1
```

PEP440 has no dots in pre-release segments. `zerv check --format pep440` accepts the SemVer
spelling and reports the normalization:

```bash theme={null}
zerv check --format pep440 1.0.0-alpha.2.post.5.dev.3+something.complex
# → Version: 1.0.0-alpha.2.post.5.dev.3+something.complex
#   ✓ Valid PEP440 format (normalized: 1.0.0a2.post5.dev3+something.complex)
```

## Docker rejects the `+` in the version

SemVer build metadata uses `+`, which docker tags forbid. Render the docker-safe form
instead, which swaps `+` for `-`:

```bash theme={null}
zerv flow --output-template "{{ semver_obj.docker }}"
# 1.0.1-alpha.10192.post.1.dev.1764902466-branch.name.1.g4e9af24
```

## Stdin piping produces nothing

Piping into `zerv version` requires the upstream command to emit `--output-format zerv`
(the RON payload), not a plain version string:

```bash theme={null}
zerv flow --output-format zerv | zerv version --source stdin --output-format pep440
```