Symptom

vectle connect (or vectle connect --repair) fails, often with a terse message or a bare JSON error code with no explanation.

Get the real error code first

Run with full diagnostics before guessing:

vectle connect --repair --no-open --json-v2

This returns a reasoncode and, for multi-client setups, a per-adapter reasoncode too. Match it below.

staterootconflict or staterootchange_unsupported

A prior interrupted or failed setup left local state behind without a valid ownership marker, or you're pointing at a different state root than the one already installed.

• If there is no real existing installation you care about, move the local Vectle config/state directory aside (do not delete blindly if you're unsure) and retry vectle connect.
• If there is a real existing installation, use vectle connect --repair instead of trying to point at a new root.

invalid_request during the initial challenge or authorization request

The installed CLI's consent contract (its declared scope list) no longer matches what the server currently requires. This happens when a server-side update adds a new consent scope before a compatible CLI version is generally available.

• Update the CLI to the latest published version and retry: npm install -g @vectle/cli@latest.
• If the newest published version still fails the same way, the rollout is likely mid-flight server-side; this is not something a client-side retry loop will fix.

releaseartifactunlisted

The CLI verifies the running version against a separately signed release manifest before proceeding, and the manifest doesn't list this exact version yet, a real but not-yet-fully-rolled-out release. Publishing to a package registry and updating the signed manifest are separate steps; occasionally the first lands before the second.

• Retry later once the manifest catches up.
• Downgrading is rarely the fix, since the manifest may also enforce a minimum supported CLI version.

clientversionunsupported on a specific adapter, such as one native coding-agent client

The locally installed native client (the actual coding-agent application, not the Vectle CLI) is older than the minimum version Vectle's release manifest requires for full native integration on that client. Other clients on the same machine can succeed independently if their versions clear the bar.

• Update that specific client application; each has its own update mechanism.
• Re-run setup scoped to just that client family and repair mode, rather than every client at once, to get a precise per-client result after updating.

Generic message: authorized, but supported native setup needs repair

This means identity and consent succeeded but one or more native client integrations aren't fully wired yet. It's a summary, not a diagnosis, always follow up with the repair plus full-diagnostics command above to see which specific reason code applies before changing anything.

Shell or PATH gotcha worth ruling out first

If a client's own CLI binary can't be found at all by your interactive shell, for example it was installed to a user-local bin directory that only one shell's startup file adds to PATH, version detection can effectively fail even though the binary and Vectle are both fine. Confirm the client's own version command resolves in the exact shell you're using before assuming Vectle itself is misdetecting it.