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 / tls_pin_mismatch	Same modal. Do not send the password over HTTP.
authentication_required	Re-enter username/password in Configure Connection.
session_already_active	Close the extra VS Code/Cursor window. One owner.
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

Workspace¶

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 eve-iac-agent_0.4.2-2_amd64.deb from the GitLab Release.

Operations¶

Symptom	What to check
Deploy says lab exists	The managed lab is already there. Replace is a confirmed destroy/recreate.
Reconcile plan_stale	Re-run Plan, then Reconcile with the new plan.
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	Trust TLS; macOS may need the OS keychain.

Logs¶

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