Troubleshooting¶

Connection¶

Symptom	What to check
Not connected	Configure Connection URL is `https://`, host reachable on `8787`
Trust / fingerprint	Compare SHA-256 with `openssl` on the EVE host. A changed cert needs a new Trust.
`tls_untrusted`	Trust has not been approved for this origin. Compare the fingerprint, then Trust. Do not send the password over HTTP.
`tls_pin_mismatch`	The live certificate changed. Compare SHA-256 on the EVE host, then Trust the new certificate.
`authentication_required`	Re-enter username/password in Configure Connection.
`session_already_active`	Close the extra VS Code/Cursor window. One owner.
CLI `tls_untrusted` / `tls_required`	Pin `--ca-file` / `EVE_IAC_CA_FILE`. `--insecure` is lab/dev only (per command, no env var). `http://` is always rejected.
CLI `--help` has no `--insecure`	Wheel older than 0.4.3 (feature floor). Install `eve_iac-0.9.0-py3-none-any.whl` from the GitLab Release.
macOS Simple Browser cert error	Import the agent cert into the login keychain as well as Trust in-UI.

Health from the EVE host:

curl -k -sS https://127.0.0.1:8787/api/v1/health

Symptom	What to check
No active lab	Open a folder that contains `IaC/<name>/.eve-iac.yml`, or Create/Import.
Edited the wrong `topology.yml`	Paths are under the lab directory from the sidebar, not the repo root.
Validate rejects interfaces	Use live template names; do not guess `Gi0/0` for IOL.
VPCS validate errors	VPCS scripts only. No `set ip`, no Cisco CLI, no instance numbers.
LOAD shows Unknown	Inspect/Plan observation. LOAD has no owned topology until you inspect.
Import: `cannot unmarshal string into … LabTask.id`	Agent older than 0.4.2-2. Install current `eve-iac-agent_0.9.0-1_amd64.deb` from the GitLab Release.

Symptom	What to check
Deploy says lab exists	The managed lab is already there. Use plan then reconcile. Replace is a confirmed destroy/recreate (`deploy --replace --yes`).
Deploy PUT every node for minutes	Agent older than 0.4.3-1 still REST-replays presentation after ZIP import. Install `eve-iac-agent_0.9.0-1_amd64.deb`.
Reconcile `plan_stale`	`confirm=true` without a matching `plan_identity`, or the classified plan changed. Re-run Plan / live-only Reconcile, then confirm with the new identity. Zero StopNode on mismatch.
`lab_locked`	Someone has the native EVE lab lock. eve-iac does not Unlock.
`lab_busy`	Another deploy/reconcile/destroy/wipe is running through this agent.
Nodes did not pick up new config	Startup-config applies on clean boot. Wipe/restart those nodes, or use Live config apply if you already authorized it.
Open Lab blank	Agent Trust is separate. Simple Browser may still need the EVE certificate in the OS trust store.
`oob_not_prepared`	Generate Inventory or `eve-iac inventory generate` ran before `.eve-iac/oob/ssh_config` existed. Prepare OOB SSH, then generate again.
`unknown_target`	`--target` is not `ansible` or `netmiko`. `eve-iac inventory targets` prints the names.

Agent journal on the EVE host: journalctl -u eve-iac-agent. IDE output channel: EVE IaC.