Troubleshooting

Connection test fails

Test on a connection’s row mints a real RUCKUS token, so a failure is always in the credentials chain. The row shows Test failed: followed by a code:

Code	Usual cause
token_mint_failed (with upstream HTTP and a status)	RUCKUS refused the credentials — wrong region, tenant ID, or secret (see the list below)
invalid_token_url	The token URL is not https, is malformed, or points at a non-public host
timeout	RUCKUS One did not answer within 15 seconds — try again
decryption_failed	The stored secret could not be decrypted — re-enter it with Edit

For token_mint_failed, in order of likelihood:

1. Wrong region. The credentials are valid but the tenant isn’t in that region. Check whether your tenant is US, Europe, or Asia — see Getting started.
2. Wrong tenant ID. The token URL includes it, so a wrong value fails at mint time.
3. Client secret mistyped. The field is write-only, so you can’t inspect what’s stored — re-enter it rather than trying to verify it.
4. Client disabled or deleted in RUCKUS One. Check the API client is still active.

The connector won’t authorize

• Redirect loop or “too many redirects” — a cookie problem during the Google sign-in hop. Use a normal (non-private) window, allow cookies for r1-mcp.lanpulse.com, remove the connector, and add it again.
• Every call fails authentication — the token was revoked, or the connector was added before sign-in completed. Remove and re-add.
• state_browser_mismatch or invalid_or_expired_state after Google sign-in — the sign-in finished in a different browser from the one that started it, or took too long. Start again in one normal window.
• You’re sent to an accept-terms page — the Terms of Service changed since you last accepted them. Accept them, and the authorization continues.
• Connector connects, but calls fail on credentials — MCP auth is fine and RUCKUS auth isn’t. Go re-run Test on the connection in the dashboard.

See Connecting to Claude.

A tool or prompt is missing

• Check the feature it belongs to is enabled on your account.
• Reconnect the connector. Tool and prompt lists are fetched when the connector refreshes; a newly enabled feature often needs a reconnect before Claude sees it.
• For Early Access features (GraphQL, Probe, Data Studio, Console, VLAN probe), confirm Early Access is unlocked on your account.
• The AI chat panel is missing from the Console page. AI chat can’t be turned on from your account — an administrator has to grant it. Ask support.

”Connection required” errors

You have more than one enabled RUCKUS connection and the call didn’t name one. This is intentional — R1-MCP will not guess which tenant you meant. Name the connection:

Using the Acme Production connection, …

See Multiple connections.

The same applies to GraphQL (call_r1_gql) and Data Studio (ds_*) calls.

Related:

Error	What it means
unknown_connection	The name didn’t match anything. Labels match exactly, including capitalization
connection_disabled	It matched a connection you’ve disabled
no_enabled_connection	Every saved connection is disabled — enable one in the dashboard
no_credentials	No connection is saved at all
no_connection	A Data Studio tool found no connection — add one in the dashboard

Rate limits (429)

GET, PUT, and DELETE are retried automatically, honoring Retry-After, with the wait capped at 5 seconds and at most 2 retries. POST and PATCH are not replayed automatically, because re-sending a create or a partial update isn’t safe.

If you’re hitting limits consistently, narrow the scope of the request — a question about one venue makes far fewer calls than one about every venue.

Calls time out or come back partial

Each code_mode run has a hard 30-second wall-clock limit. A very broad request either returns partial results after the 20-second warning, or is stopped with “code_mode exceeded its 30s wallclock limit”. Nothing continues on its own — ask again, with a narrower scope.

The fix is scope, not retries: ask for one venue, one time window, one device.

If the run was making changes, check what landed before retrying: writes it had already sent may still complete after the timeout.

The FastIron syntax is wrong

Almost always a firmware train mismatch. R1-MCP scopes documentation search to one release, and defaults to the newest train — which may not be your switch’s.

Tell it the firmware: read switchFirmwareVersion from R1 or run show version, and say “this switch is on 10.0.10”. The patch level doesn’t matter; the minor does. Never mix trains within one switch’s config. See ICX.

device_cli can’t reach a device

A prompt timeout — no prompt after login, or the session closing right after login — usually means the device is offline or unreachable, not that the call was wrong. Confirm the device is online with a status query before retrying; each first-call retry opens a fresh session, so blind retries against a dead target just accumulate.

Also check you passed the device serial number, not its MAC.

Error	What it means	What to do
no_prompt_after_login / ws_closed_after_login (switch), no_ap_prompt (AP)	The device is most likely offline or unreachable	Confirm it is online before retrying
jwt_mint_forbidden	The connection’s R1 API client isn’t allowed to open this CLI. For an AP, the connection is read-only — AP CLI needs a read-write one	Re-run with connection naming a read-write connection; the reply’s hint says the same
connection_mismatch	You named a different connection while reusing an open session	Close the session and open a new one on the other connection
busy	Another call on the same session is still running	Wait for it to return, then retry
command_in_flight	A previous command is still streaming	Poll it to completion first
session_lost	The session dropped or was reclaimed after sitting idle	Open a fresh session
switch_credentials_unavailable	R1 has no switch login credential for the venue	Check the venue’s switch settings in RUCKUS One
login_incorrect	The switch rejected the login	Check the venue’s switch credential in RUCKUS One

Without a connection, device_cli uses your default connection. If that connection is disabled, the call fails with connection_disabled — enable it, make an enabled connection the default, or name one with connection. See Multiple connections and Live CLI.

A MOP replay stops on write arming

• write_arming_required — the run contains writes to a RUCKUS One tenant. Claude should show you the write_targets tenants and, once you agree, re-send with armWrites: true.
• write_not_armed — a step writes to a tenant that wasn’t in the run’s armed set. Re-create the run with armWrites: true.

See Live CLI and MOPs.

A call came back confirm_required with status 0

That is Write Guard, not an HTTP failure. Nothing was sent to RUCKUS One. Claude shows you the preview, and after you approve it, sends the same call again with the confirmation token.

Claude paraphrased console output instead of showing it

Ask for it verbatim. R1-MCP’s instruction is to surface live console output in a fenced code block labeled with its command — if you only got a summary, “show me the raw output” gets you the rest.

A copy, backup, or restore refuses

Each of these is a deliberate stop, not a bug.

Gates:

Error	What it means	What to do
target_not_empty	The target venue already has onboarded devices or activated config	Confirm it really is the right target, then re-plan with acceptWarnings: true
missing_capture	The plan needs a write-only secret the source tenant masks on read	Supply it in the bindings map at run start — the plan’s operatorInputRequired lists exactly which
snapshot_incomplete	You planned from an extract that never finished	Call venue_extract with the same snapshotId until complete: true

Caps:

Error	What to do
snapshot_too_large / backup_too_large	Over the 5 MB config cap — restrict domains and capture the rest separately
snapshot_limit_reached	20 snapshots — delete one with venue_snapshot_delete
backup_limit_reached	50 backups, and nothing expires them — backup_delete one first
plan_invalid	The compiled MOP is over its step cap — plan each subset of domains into its own MOP

Arguments:

Error	What it means
ambiguous_target	You passed both target.venueId and target.newVenue — pass exactly one
ambiguous_source	You passed both snapshotId and backupId — they’re alternative sources for the same diff
template_requires_new	Template mode always creates a new template, so it needs target.newVenue
not_an_element_snapshot	That snapshot is a venue extract — continue it with venue_extract, not element_extract
element_selector_required	Identify the element with an id (preferred) or an exact name
snapshot_blob_missing / backup_blob_missing	The stored config is gone; delete the row and capture again

Also check complete on the snapshot before planning. An extract that stopped partway leaves objects without captured definitions, and the plan skips them with a warning rather than guessing. See Venue config copy.

An element copy produced no MOP at all

A same-tenant element copy writes nothing unless you rename what it creates: the copy names every object exactly as the source does, so each collides with itself and R1 refuses the duplicate name. Pass a rename to element_copy_plan (for example a new name for the element), name a different targetConnection, or use a venue copy if you want the object on another venue in the same tenant. See Copying one object.

The copy joined an object I didn’t expect

A copy into a tenant you have copied into before adopts an existing shared object of the same name by default — it wires your copy to that object rather than creating a second one. Matching is by name only; the contents are never compared.

Every adopted object is named in the plan’s warnings. If you wanted a separate object, rename the source before extracting; if you wanted the existing one brought in line with the source, plan with sharedCollision: "overwrite" — but read what an overwrite does to other venues first, because an undo cannot reverse it.

Relatedly, venue_copy_verify reporting complete: true does not mean every object was compared — read verifyLimits and subCollections.

Undo or verify says run_not_found

Replay runs are kept for 7 days. After that, venue_copy_undo and element_copy_verify with a runId return run_not_found. Undo a copy, or verify it by run, within a week of running it.

Probe calls come back not_linked

Your account hasn’t completed the one-time consent on the Probe MCP side. The error carries a link_url — open it once in a browser and the calls start working. probe_link_status reports the current state at any time.

probe_offline is different: the consent is fine and the probe itself isn’t reachable. companion_unavailable means the deployment has no probe integration wired at all. unknown_tool means the tool named isn’t one Probe MCP offers, and ambiguous_probe (from probe_reconcile) means you have more than one probe and didn’t say which. Other codes — probe_unreachable, bad_assertion, companion_disabled, no_probes, no_cloud_devices, r1_query_failed — are explained in Probe error envelopes.

A probe tool I expected isn’t available

R1-MCP exposes 15 read-only probe tools — the CLI, packet-capture, traffic, and egress tools are not among them, and probe_call refuses a name outside that list. This is narrower than what the link permits, deliberately; see Two boundaries, not one.

A Data Studio dashboard is empty or invisible

Two distinct causes, and they look similar:

• You can’t see it at all. New dashboards are drafts, and a draft is visible only to the API client that created it. It needs published: true.
• It’s visible but the charts aren’t there. Charts must be attached with dashboards: [<id>] when created or updated. Referencing chart ids in positionJson alone does not create membership.

For a chart that saves but throws “Unexpected Error” on render, ds_diagnose_charts replays the real render and reports Superset’s own error. See Data Studio dashboards.

Two more chart errors:

• datasource_id_mismatch — the dataset id disagrees between the tool argument, params, and queryContext, so the chart is refused. Such a chart would save but render empty; make all three match.
• DATASTUDIO-20010 — RUCKUS allows at most 6 dimensions per chart, and the chart won’t render until you reduce them. See RUCKUS’s chart limits.

Live Console problems

• watch_limit_reached — you have 100 active watches. Clear one before adding another.
• The sparklines stopped moving. Metric polling pauses after 15 minutes to spare the R1 API; webhook events keep updating. Press Resume on the banner.

See Live Console.

Test bed and webhook errors

• no_live_backup from config_diff — RUCKUS One has no usable config backup for that switch, and config_diff won’t create one (that would evict one of the few backups RUCKUS keeps). Run testbed_capture for a fresh capture. See Test beds.
• nothing_to_apply from testbed_apply — every device is already where the plan puts it.
• Your webhook receiver answers 401 unauthorized — the secret RUCKUS One sends doesn’t match the one R1-MCP issued. Re-copy it into the webhook settings. See Webhooks and analytics.

An endpoint behaves differently from the spec

That happens — the RUCKUS spec doesn’t capture everything. Ask Claude to save an endpoint note describing the quirk; it’s private to you and resurfaces whenever that endpoint’s details are looked up again. See Core tools.

If it’s a spec-wide problem worth everyone knowing, tell support — notes can be promoted to global visibility.

Still stuck

Contact support. Include the tenant region, roughly when the request ran, and the error text Claude reported — R1-MCP surfaces real R1 status codes and bodies, so that text is usually diagnostic.