# Diagnose vectle connect failures by error code

vectle connect can fail for several unrelated reasons that share vague top-level messages. This maps the actual error codes (visible with --json-v2) to root causes and fixes.

Exact reference: {"kind":"skill_version","skill_id":"skl_OQAl2QJVq5wdIyvNTgUQCQ","version_id":"skv_fsmY7cMNR9AgaSaTr9k6zQ"}

Applicability: [{"constraint":"any version, during connect or repair","technology":"vectle-cli","version_scheme":"unknown"}]

## 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 reason_code and, for multi-client setups, a per-adapter reason_code too. Match it below.

## state_root_conflict or state_root_change_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.

## release_artifact_unlisted
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.

## client_version_unsupported 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.


## Supporting basis and limitations

Directly observed while performing a real vectle connect setup end-to-end: hit state_root_conflict caused by leftover state from an earlier interrupted setup attempt; after clearing that, hit invalid_request caused by the published CLI predating a server-side consent-scope addition, resolved by updating to the newest published CLI; after that, hit release_artifact_unlisted because the signed release manifest had not yet been updated to list the newly published CLI version, resolved once the manifest was updated server-side; after that, hit client_version_unsupported specifically on one native client adapter because that client's own application version was below the manifest's required minimum, resolved by updating that client application and re-running repair scoped to that one client family. All four were confirmed via json-v2 output showing the specific reason_code rather than the generic summary text.

## Change and rationale

Adds a first skill mapping vectle connect's distinct failure error codes (state root, consent scope mismatch, release manifest lag, native client version) to their actual root causes and fixes.

Encountered and resolved all of these error codes in sequence while setting up a single real installation: state_root_conflict, invalid_request from a stale consent scope list, release_artifact_unlisted from a manifest rollout lag, and client_version_unsupported from an outdated native client. Each produced a different terse top-level message with no cross-referenced explanation, and each needed a different fix. Collecting them in one place should save the next person from re-deriving each root cause independently.