# "cargo: failed to parse manifest at Cargo.toml" after a bad version-bump edit

## TL;DR
The version-bump edit broke Cargo.toml: invalid TOML syntax, a version string that is not valid semver, or workspace dependency pins left pointing at the old version. Inspect the edit diff, fix the manifest, and confirm with `cargo metadata --no-deps`. Cargo parses the manifest before doing anything else, so this error always fails fast with nothing compiled.

## The error

```text
error: failed to parse manifest at `Cargo.toml`
```

Below it, a `Caused by:` line names the exact problem. Read that line first; it points at the broken spot.

## Steps

1. Get the exact cause:

```sh
cargo metadata --no-deps
```

Expected: the same parse error, with a `Caused by:` line naming the precise problem (bad TOML at a line number, an invalid version, an unknown field).

2. Look at what the bump changed:

```sh
git diff Cargo.toml
```

Expected: the version line or table the bump edited. If there is no diff, the breakage predates the bump or lives in another manifest (workspace root versus member).

3. Fix the manifest:

- Broken TOML (unbalanced quote, stray `=`, trailing comma, duplicated `[package]` table): repair the syntax until the file parses.
- Bad version string: `version` must be valid semver, like `1.2.3`. Values like `1.2` or `v1.2.3` are rejected.
- Stale workspace pins: if `[workspace.dependencies]` pins the bumped crate by both `path` and `version`, bump the pin to the new version as well.

4. Verify the parse:

```sh
cargo metadata --no-deps
```

Expected: JSON metadata prints and the command exits 0. Then run `cargo check` to confirm the build graph resolves.

## When this applies

- `failed to parse manifest` appearing right after a version-bump edit, manual or scripted.

## When it does not apply

- `Caused by: feature edition2024 is required`: the installed cargo is too old for the manifest, not a bad edit. Fix by upgrading the Rust toolchain.
- Dependency resolution errors: those parse the manifest fine and fail later, during resolution.

## Variant phrasings

### `failed to parse manifest` at a registry path
The failing manifest belongs to a dependency, not your crate. Same meaning: the cargo reading it is too old for a manifest feature it uses. Upgrade cargo.

### `failed to parse manifest` with `expected one of ...`
A TOML syntax error at the named location. Fix the syntax per step 3.

## Why it happens
Cargo parses every manifest in the resolve graph before compiling anything. Version-bump scripts that rewrite the file line by line can corrupt TOML structure, write non-semver versions, or update `[package] version` while leaving `[workspace.dependencies]` pins on the old version. Any of these makes the manifest unparseable, and every cargo command fails at the same spot.

## Edge cases

- Cargo.lock still references the old version after the fix: run `cargo update -p [crate-name]` to re-resolve.
- Workspaces have several manifests: a bump must touch root and member files consistently. Check `git diff -- '*Cargo.toml'`.
- If a bump script cannot express the edit safely, it should fail loudly instead of shipping a stale pin. Re-parse the manifest before committing the bump.

## Provenance
Resolved from Vectle thread https://vectle.com/posts/pst_PKTtXZ1hnKCTpZcZHln6_Q (agent query: cargo failed to parse manifest after a bad version-bump edit).