Troubleshooting
Work from the error you were given. Most failures belong to one of four layers: the certificate, the address, the SmartZone credentials, or the connector.
Save & detect fails
Section titled “Save & detect fails”A failed save reads Not saved: <code>: <detail>, and a failed Test
connection reads Test failed: <code> — <detail>. The code is the same either
way; the headings below use the test form.
”Test failed: invalid_host”
Section titled “”Test failed: invalid_host””The controller could not be reached at all. In order of likelihood:
- The certificate is self-signed. This is the most common cause by a wide margin. The TLS handshake fails before SmartZone sees your username, so the error names the connection rather than the credentials. Install a publicly trusted certificate — see Controller requirements.
- The certificate does not match the hostname you entered. A certificate
for
sz.example.comdoes not satisfy a connection made to an IP address. - The port is wrong or closed. Default is 8443; it must be reachable from the public internet.
- DNS resolves somewhere unreachable. A name that does not resolve at all
is
forbidden_host, below. - The controller did not answer within 15 seconds.
”Test failed: forbidden_host”
Section titled “”Test failed: forbidden_host””The address you entered is not publicly routable, and SZ-MCP refuses it before
making any request. The detail names the reason — for example IPv4 10.1.2.3 is in a reserved/private range.
Private, loopback, link-local, CGNAT and multicast ranges are all refused, as
are hosts ending .local, .internal or .localhost, and non-canonical IP
literals such as 2130706433 or 127.1. The full list is in Controller
requirements.
A hostname is refused the same way when it resolves to a private address, or when it does not resolve at all:
| Detail | What to do |
|---|---|
"<host>" resolves to <ip>, a reserved/private address | Publish the controller under a public address, or use the controller tunnel |
"<host>" does not resolve to an address | Check the name and its DNS records |
could not resolve "<host>"; try again | The DNS lookup failed; try again |
<host> is not this organisation's controller tunnel | Use your own tunnel’s hostname, from the Private controller (tunnel) card |
A controller on a private LAN has to be published, or reached through the controller tunnel (limited rollout: contact support to have it enabled), before SZ-MCP can reach it.
”Test failed: forbidden_port”
Section titled “”Test failed: forbidden_port””The port is not one of the two allowed: port <n> is not allowed; use 8443 or 443. Pick 8443 or 443 in the Port field.
”Test failed: not_smartzone”
Section titled “”Test failed: not_smartzone””Something answered at that host and port, but not as a SmartZone: no SmartZone API at https://<host>:<port>/wsg/api/public/apiInfo (http_<status>). Usually the
host or port points at another service, such as a reverse proxy that does not
forward /wsg/api. No login was attempted, so this costs nothing against a
lockout policy.
”Test failed: login_failed”
Section titled “”Test failed: login_failed””The controller answered and rejected the login. The detail carries the upstream
status, such as http_401.
Check the username and password against the SmartZone admin UI. The detail is deliberately terse — SmartZone’s own error bodies can disclose account-lockout state, so only the status code is kept; the body is neither logged nor returned.
”Not saved: invalid_body”
Section titled “”Not saved: invalid_body””A field failed validation — most often the host. The Host field takes
sz.example.com, not https://sz.example.com and not sz.example.com/wsg:
host must be a bare FQDN or IP (no scheme, path, port or user). Remove the
scheme and any path. The port goes in its own field.
”Not saved: enter the password to save a new host or port.”
Section titled “”Not saved: enter the password to save a new host or port.””A new host or port needs the password again, so the stored password is never sent to a host it was not entered for. Type the password and save. Only the username and label can change without it.
Test connection is greyed out
Section titled “Test connection is greyed out”Test connection checks the saved login, so it is disabled while the form has unsaved changes. A note under the form names the saved login. Click Save & detect first, then test. If every field is greyed out, you are not an organisation admin: “Only organisation admins can change or test the controller login.”
Did the version change after a save without a password?
Section titled “Did the version change after a save without a password?”No. Version detection only runs when a password is supplied. If you changed only the username or label and left the password blank, the previously detected version was kept. Click Test connection to force detection to run again.
Controller tunnel errors
Section titled “Controller tunnel errors”These appear only when the login uses your controller tunnel. Cloudflare’s edge answered, not the controller.
| Code | Detail | What to check |
|---|---|---|
tunnel_down | no cloudflared is connected to the tunnel: start it next to the controller | Run the command from the Private controller (tunnel) card; the card shows waiting for cloudflared until it connects |
tunnel_origin_unreachable | cloudflared is running but cannot reach the controller at the LAN address the tunnel names | The controller’s address and port on your network; Change address on the card fixes a moved controller |
tunnel_access_denied | Cloudflare Access refused the tunnel's service token | Contact support |
The card itself says “Controller tunnels are in limited rollout; ask an sz-mcp admin to enable them for your account.” until tunnels are enabled for you, and Remove is refused while the login still uses the tunnel (“The controller login uses this tunnel: remove or change the login first.”).
A test that reports failure with a green status
Section titled “A test that reports failure with a green status”The credentials test endpoint answers HTTP 200 even when the test fails,
carrying { "ok": false, "error": "…" } in the body. The dashboard reads ok
and renders the failure correctly, so you will see it in the UI — but anything
scripting the API directly must check ok rather than the status code.
The same principle applies inside code mode: call returns HTTP failures as
values with ok: false rather than throwing. See Code mode
primitives.
The connector will not authorize
Section titled “The connector will not authorize”Claude loops through sign-in without reaching consent
Section titled “Claude loops through sign-in without reaching consent”Your session cookie is not surviving the redirect back from Google. Sign in at sz-mcp.lanpulse.com first, confirm the dashboard loads, then add the connector in Claude — the consent screen reuses that session rather than starting a fresh sign-in.
If it persists, remove the connector in Claude and add it again, so Claude re-registers from a clean state.
”Please accept the Terms and Privacy Policy to continue.”
Section titled “”Please accept the Terms and Privacy Policy to continue.””The consent screen requires the terms checkbox on your first authorization. Tick it and choose Allow again.
The connector is authorized but Claude sees no tools
Section titled “The connector is authorized but Claude sees no tools”tools/list returns exactly one tool, code_mode. If Claude reports none,
the bearer token is not being accepted — remove and re-add the connector.
”rate_limited” when adding the connector
Section titled “”rate_limited” when adding the connector”Client registration is capped at 20 per IP per hour. Normal use registers once, so hitting this means something is re-registering in a loop. Wait an hour, then add the connector once and let it complete.
Errors from inside code mode
Section titled “Errors from inside code mode””No SmartZone controller is saved for this organisation”
Section titled “”No SmartZone controller is saved for this organisation””call returned no_credentials. The connector is authorized but no controller
is saved for its organisation — or it was deleted. An organisation admin saves
credentials on Configure › Controller; no reconnect is needed afterwards.
”code_mode exceeded its 30 s wall-clock limit”
Section titled “”code_mode exceeded its 30 s wall-clock limit””The program ran past its 30-second limit and came back as { "error": "timeout", … }. It is usually an unbounded pagination loop. Ask for the work in smaller
pieces — each code_mode call gets a fresh clock. If the result’s writesSent
lists any writes, they may still have been applied: check the controller’s
current state before retrying them. See
Limits and quotas.
”code must be under 20,000 characters”
Section titled “”code must be under 20,000 characters””The generated program exceeded the source limit. Ask for a narrower task.
Repeated 401s from the controller
Section titled “Repeated 401s from the controller”A 401 triggers one automatic ticket refresh and retry. If the fresh login is
rejected, call fails with login_failed — the password changed or the account
was locked; run Test connection to confirm. If the login succeeds and the
endpoint still answers 401, that second 401 is returned as-is: the endpoint
refused a fresh ticket, so check the SmartZone account’s role and domain for that
resource.
A 404 on an endpoint that discovery found
Section titled “A 404 on an endpoint that discovery found”The bundled endpoint catalogue describes a v14_0 (SmartZone 7.2.0)
controller. If yours runs
an older version, an endpoint in the index may not exist on it. This surfaces as
a 404 from call rather than as a discovery failure. See The two API
surfaces.
A program that calls list_tag_groups fails
Section titled “A program that calls list_tag_groups fails”list_tag_groups no longer exists on either namespace. It was removed because
the SmartZone specs define no tag groups, so it only ever returned an empty
list. The group argument on list_tags went with it. Start discovery with
list_tags(), which takes no arguments. See Finding the right
endpoint.
Where is a POST’s request body in get_endpoint_details?
Section titled “Where is a POST’s request body in get_endpoint_details?”In requestBody, as { required, contentType, schema }. The specs are Swagger
2.0, where a request body is a parameters entry with in: "body"; SZ-MCP
lifts it into requestBody for you. An upload (in: "formData") shows
requestBody with fields instead of schema, and an operation that takes no
body, such as POST /restart, shows requestBody: null. See Code mode
primitives.
Everything worked yesterday and fails today
Section titled “Everything worked yesterday and fails today”| Symptom | Likely cause |
|---|---|
Sudden login_failed | The SmartZone password changed, or the account was locked or disabled |
Sudden invalid_host | The controller’s certificate expired, or DNS/port changed |
403 on calls that used to succeed | The SmartZone account’s role or domain scope was narrowed |
| Connector stopped working entirely | Credentials were deleted on the dashboard, the connector was revoked under Connected clients or removed in Claude, or you were removed from the organisation |
Sudden tunnel_down | cloudflared next to the controller stopped |
Still stuck
Section titled “Still stuck”Contact support.neuralconfig.com. Include the exact error text, whether it came from the dashboard or from Claude, and your controller’s SmartZone version.
Never send your SmartZone password.