From 24bd1c80735bb7fa0412f467b466f3f402535f91 Mon Sep 17 00:00:00 2001 From: Leo Miranda Date: Fri, 23 Jan 2026 22:54:23 +0000 Subject: [PATCH] Add "lessons/patterns/setup-wizard-url-format-mismatch" --- ...ns%2Fsetup-wizard-url-format-mismatch.-.md | 42 +++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 lessons%2Fpatterns%2Fsetup-wizard-url-format-mismatch.-.md diff --git a/lessons%2Fpatterns%2Fsetup-wizard-url-format-mismatch.-.md b/lessons%2Fpatterns%2Fsetup-wizard-url-format-mismatch.-.md new file mode 100644 index 0000000..7fa3954 --- /dev/null +++ b/lessons%2Fpatterns%2Fsetup-wizard-url-format-mismatch.-.md @@ -0,0 +1,42 @@ +## Context + +When running `/cmdb-assistant:initial-setup` on a fresh server (banditlabs), all NetBox MCP tools failed with JSON parsing errors despite the API returning valid responses. + +- Command/tool: `dcim_list_devices`, `dcim_list_sites` +- Error: `Invalid JSON response from NetBox: Expecting value: line 8 column 1 (char 7)` + +## Problem + +The `/initial-setup` command asked users for a "NetBox server URL" with example `https://netbox.company.com`, but the `NetBoxClient` expected the full API URL including `/api` suffix. + +**Root cause:** Inconsistency between setup wizard and code expectations: +- Setup saved: `NETBOX_API_URL=https://netbox.hotserv.cloud` +- Code expected: `NETBOX_API_URL=https://netbox.hotserv.cloud/api` + +The validation test in the setup wizard **incorrectly** appended `/api/` to the URL when testing, making it pass even though the saved config was wrong. This masked the bug during setup. + +## Solution + +1. Updated setup wizard example to show URL with `/api` suffix +2. Added instruction to auto-append `/api` if user forgets +3. Fixed validation test to use URL as-is (consistent with actual usage) + +**PR:** #132 +**Files:** `plugins/cmdb-assistant/commands/initial-setup.md` + +## Prevention + +When writing setup wizards that save configuration: +1. **Example values must match exact format expected by code** +2. **Validation tests must use config exactly as saved** - don't transform it +3. **Document URL format requirements explicitly** in prompts +4. **Test fresh installations** on new machines, not just existing setups + +## Related + +- Issue: #126 +- PR: #132 +- Component: cmdb-assistant, NetBox MCP + +--- +**Tags:** cmdb-assistant, netbox, setup-wizard, configuration, url-format, validation, bug-fix \ No newline at end of file