1

lessons/patterns/setup-wizard-url-format-mismatch

Leo Miranda edited this page 2026-01-23 22:54:23 +00:00

Table of Contents

• Context
• Problem
• Solution
• Prevention
• Related

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: [Bug] NetBox MCP tools fail JSON parsing despite valid API response (#126)
• PR: fix(cmdb-assistant): correct NetBox API URL format in setup wizard (#132)
• Component: cmdb-assistant, NetBox MCP

---

Tags: cmdb-assistant, netbox, setup-wizard, configuration, url-format, validation, bug-fix