Troubleshooting

A consolidated list of the things that break for first-time setups. Symptom → likely cause → fix.

Auth and credentials

401 from a CLI call. Your saved session expired or your API key was revoked. Run dsp login again, or generate a new key at app.display.dev/keys and update DISPLAYDEV_API_KEY (or ~/.displaydev/config.json).

401 from an MCP tool call (any host). Three paths, three fixes:

• Custom connector (Claude Desktop, Claude.ai): the connector grant was revoked from app.display.dev/settings/connectors, or the host lost its stored connector credentials. Reopen Settings → Connectors in the host and reconnect.
• Local stdio (dsp mcp subprocess): run dsp login from a terminal, then restart the assistant.
• Remote via mcp-remote + API key: rotate the API key and update the --header "Authorization: Bearer ..." argument in your config file.

CLI says "Not authenticated" but I just ran dsp login. Make sure DISPLAYDEV_API_KEY isn't set to an expired key in your shell profile — env-var beats ~/.displaydev/config.json in the precedence order. Run unset DISPLAYDEV_API_KEY in your shell and retry.

MCP setup

Tool doesn't appear after restart. The host's config file has a JSON or TOML syntax error. Validate before restarting:

• JSON (claude_desktop_config.json, .claude/settings.json, .mcp.json, ~/.cursor/mcp.json): jq . < <path>
• TOML (~/.codex/config.toml): any TOML linter, or just paste it into the Codex CLI which will refuse to start with a clear error.

command not found in the MCP log (Claude Desktop, local stdio). Claude Desktop doesn't expand ~ or use the shell PATH. Run which dsp and paste the absolute path into the command field.

First MCP call hangs (Cursor with npx, Claude Desktop with npx mcp-remote, etc.). The first invocation downloads the package; this can take 30–60 seconds. Subsequent calls reuse the npx cache.

Tool list is empty after editing config (Cursor). Cursor caches MCP servers per-window. Reload the window with ⌘⇧P → "Reload Window".

Codex says my server isn't registered after I edited config.toml. Codex caches MCP server registrations at session start. Exit (Ctrl+D or /exit) and start a new session.

Publishing

402 plan_required on dsp publish. You hit a tier-gated capability — usually --visibility private (Pro+) or the gated-artifact cap on Free (10 non-public artifacts). The CLI prints an upgrade URL on the next line. See Plans & features.

404 on a dsp share / dsp rename / dsp delete. The shortId is wrong, the artifact was deleted, or you're authenticated as a different organization. Run dsp find to confirm what your current org can see.

A republish (dsp publish --id <shortId>) succeeded but the URL still shows the old content. The viewer fetches latest version by default. If a stale page is open in a browser, hard-refresh (⌘⇧R / Ctrl+Shift+R). The Worker doesn't cache aggressively across versions, but browser caches persist.

Search and view

Search palette shows "Couldn't load search index." The JSON index failed to fetch (network blip or CDN miss). Click Retry, or refresh the page.

Browser shows an artifact URL with /_v/3 and I want the latest. The URL is a pinned-version permalink. Drop the /_v/3 suffix to get the latest. (See Concepts → Version.)

Still stuck

If your error isn't listed here, the fastest path is a one-line message at [email protected] with:

• The exact command you ran (or the JSON/TOML config block you added).
• The full error message, including HTTP status if shown.
• Your CLI version (dsp --version).