Troubleshooting

First, read the shape of the failure

Two different things can go wrong and they look different:

	Looks like	Means
Input validation	Error executing tool dataverse_x: 1 validation error for dataverse_xArguments followed by a field name and a reason	The call never left your machine. Wrong argument, bad URL, or a blocked host.
Everything else	JSON: {"error": true, "message": "..."}	The call ran. Dataverse, the network, or the credential failed.

Server logs go to stderr, shown by your client as server output — that is where startup warnings, retry notices and the detail behind Unexpected error live. Check it before anything else.

Symptom → cause → fix

Symptom	Cause	Fix
Credential acquisition timed out after 30s.	Browser sign-in with MFA outran the 30 s cap	Raise DATAVERSE_AUTH_TIMEOUT_SECONDS to 120, then retry the tool call
No browser appears and the call hangs, then times out	interactive opens a browser and a 127.0.0.1 listener on the machine running the server — a remote host or container has no desktop session to show it	Switch to DATAVERSE_AUTH_TYPE=azure_cli and az login on that host
Authentication failed. Run az login to refresh your Azure CLI session...	The az session expired or is signed in to the wrong tenant	az login (add --tenant your-tenant-id), then restart the server
Under interactive on headless Linux, the first tool call fails on the token cache	No OS secret store (libsecret / GNOME Keyring) and encryption is required by default	Install libsecret, or set DATAVERSE_TOKEN_CACHE_PERSIST=false, or accept the trade-off with DATAVERSE_TOKEN_CACHE_ALLOW_UNENCRYPTED=true — see Authentication
A browser prompt on every restart	DATAVERSE_TOKEN_CACHE_PERSIST=false, or the AuthenticationRecord sidecar could not be read	Check stderr for Could not load AuthenticationRecord; confirm the sidecar directory is writable
Two server entries keep signing each other out	They share the default token cache filenames	Give each a distinct DATAVERSE_TOKEN_CACHE_PROFILE
Startup fails naming DATAVERSE_TOKEN_CACHE_PROFILE	The value contains a character outside [A-Za-z0-9_-]	Rename the profile; it refuses to sanitise rather than risk two profiles sharing one cache
...is not in the configured DATAVERSE_WHITELIST	The host is not approved on this server	Add the hostname to DATAVERSE_WHITELIST and restart, or use the server entry that owns that environment
DATAVERSE_REQUIRE_WHITELIST is set but DATAVERSE_WHITELIST is empty	Fail-closed posture with nothing allowed	Populate DATAVERSE_WHITELIST (the same error is logged at ERROR level on startup)
Dataverse returned HTTP 403: ...	Dataverse itself refused — the signed-in user lacks the privilege	Not a server setting. Check the user's security role, or run dataverse_audit_user_access
The agent says a tool doesn't exist	It was never registered — write/delete gate closed, or its category excluded	See below
Response too large (N MB). Narrow the query with select/top/filter.	The serialised response exceeded 5 MB	Add select, lower top, add a filter, or use the tool's own lever (include_content, include_solutions, max_chars)
String should have at most 2000 characters on fetch_xml	Only dataverse_validate_fetchxml caps FetchXml at 2,000 characters	Trim whitespace and comments, cut <attribute> elements, validate <link-entity> branches separately
Dataverse rejected the request URL as too long (HTTP 414)	The FetchXml travels in the query string and percent-encoding roughly doubles it	Same trim; the message reports the raw and encoded lengths
String should match pattern '^[a-zA-Z_][a-zA-Z0-9_]*$'	A logical / schema / entity-set name argument contains a hyphen, dot, space or leading digit	Use the Dataverse logical name (new_project, accounts) — lowercase, underscores only
Invalid GUID format: '...'	A record or component id is not a canonical 8-4-4-4-12 GUID	Pass the raw GUID with no braces or surrounding quotes
Extra inputs are not permitted	An argument name the tool does not define	See below
Batch operations containing POST/PUT/PATCH methods require DATAVERSE_ALLOW_WRITE=true...	dataverse_execute_batch is always registered but gates its own operations	Enable the flag, or split the read operations into their own batch
A form or view read back unchanged after an edit	Reads return the published version	Use dataverse_retrieve_unpublished, or publish first — see below
Record counts look wrong, or every count is 0	dataverse_get_total_record_counts reads a snapshot up to 24 hours old	Use dataverse_count_records for an exact live count
Could not reach <host>: ...	DNS, proxy or firewall — not authentication	Confirm the host resolves from the machine running the server
Unexpected error in dataverse_x. See the server logs for details.	Unhandled exception; the detail is withheld deliberately (it can carry internal paths)	Read stderr, then open an issue with that traceback

403 versus a whitelist rejection

They are easy to confuse and have opposite fixes.

Whitelist — an input-validation failure. No HTTP request was made, no token was minted:

Error executing tool dataverse_whoami: 1 validation error for dataverse_whoamiArguments
params.dataverse_url
  Value error, dataverse_url host 'other.crm.dynamics.com' is not in the configured
  DATAVERSE_WHITELIST. Add it to DATAVERSE_WHITELIST to permit access to this environment.

Fix it in the MCP client config, then restart the server.

403 — Dataverse answered. The call reached the org and was refused there:

{ "error": true, "message": "Dataverse returned HTTP 403: [<odata-code>] <Dataverse's own message>" }

Fix it in Dataverse: the signed-in user needs the privilege. dataverse_whoami will still succeed, which is a useful confirmation that the environment and credential are fine and only the privilege is missing.

"That tool doesn't exist"

Gated tools are not registered, so the client genuinely cannot see them. Three reasons, in order of likelihood:

1. The write or delete flag is off. Only the exact string true (any case) enables DATAVERSE_ALLOW_WRITE / DATAVERSE_ALLOW_DELETE; "1", "yes" and "True " with a trailing space all mean off, silently.
2. DATAVERSE_TOOLS excludes its category. Check the startup line DATAVERSE_TOOLS active categories: ....
3. A typo in DATAVERSE_TOOLS. Unknown tokens are dropped with a warning naming them: DATAVERSE_TOOLS: unknown category 'scheme' — ignored (known: apps, connections, core, ...). DATAVERSE_TOOLS=scheme leaves you with core only.

Every change here needs a server restart — the configuration is read once at import. See Tool-Categories and Safety-and-Permissions.

Unknown parameter rejected

Every input model sets extra='forbid', so a misspelled or invented argument fails rather than being ignored:

params.topp
  Extra inputs are not permitted [type=extra_forbidden, input_value=5, input_type=int]

This is usually the agent guessing at a parameter that belongs to a different tool. The field name after params. tells you what it invented; the tool's entry in Tool-Index lists what it actually accepts. Re-prompting with the correct argument name normally resolves it in one turn.

Published versus draft

Reads of forms, views and apps return the published version. Immediately after dataverse_set_formxml or dataverse_update_view, a read looks unchanged — the write landed, the read is stale.

Two ways forward:

• dataverse_retrieve_unpublished reads the draft. Supported entity sets: savedqueries, systemforms, appmodules, webresourceset. Not sitemap — the platform refuses the message for that type. Large XML and binary columns are excluded unless you name them in select.
• dataverse_publish_customizations publishes, after which the ordinary read is correct.

Reading the published row, editing it, and writing it back will silently discard your own unpublished changes. Read the draft first.

Still stuck

Capture the stderr output around the failure and open an issue. Redact org URLs, tenant IDs and GUIDs.