Skip to content

Troubleshooting

The errors users hit most often, and how to clear them.

On this page

Find a symptom, check the likely cause, and follow the recovery step.

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 API keys and update DISPLAYDEV_API_KEY.

401 from an MCP tool call. Use the recovery step for your connection:

  • OAuth connection: the connection was revoked from Connected apps, or the host lost its credentials. Reconnect Display.dev from the host's MCP settings.
  • Local stdio (dsp mcp subprocess): run dsp login from a terminal, then restart the assistant.
  • Remote with an API key: rotate the key and update the authorization header in the host's configuration.

CLI says "Not authenticated" but I just ran dsp login. An expired DISPLAYDEV_API_KEY takes precedence over the saved session. Run unset DISPLAYDEV_API_KEY and retry.

MCP setup

Tool doesn't appear after restart. The host's configuration may have a JSON or TOML syntax error. Validate it before restarting:

  • JSON: set CONFIG_PATH="$HOME/.cursor/mcp.json", then run jq . "$CONFIG_PATH".
  • TOML: run a TOML linter, then restart the host.

command not found for a local MCP server. Run which dsp. If the host cannot find the command, use the printed absolute path in its command field.

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.

create_upload works, but the file transfer cannot connect. The code-execution environment cannot reach api.display.dev. Allow outbound HTTPS to that domain, then start a new execution task. In Claude Cowork, Team and Enterprise administrators can add the domain under the organization's code-execution capabilities. Personal Pro and Max accounts cannot currently add it. Use inline content when the source is small enough, dsp publish where the file exists, or dashboard upload.

publish returns upload_unavailable. The 15-minute upload capability expired, the file was not transferred, or the staged upload is no longer available. Call create_upload again, transfer the file, and publish with the new upload_id. The initiating execution trace may show the temporary bearer, but do not copy it into a final response, shared diagnostic, generated artifact, or unrelated tool call.

publish returns upload_size_mismatch. The transferred byte length does not match size_bytes. Measure the raw file again, create a new upload, and send the file without encoding or wrapping it in JSON.

Publishing

402 plan_required on dsp publish. You reached the Free limit of 10 gated artifacts or another plan limit. Private is available on every plan. The CLI prints an upgrade URL on the next line. See Plans and limits.

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 list to confirm what your current org can see.

dsp edit says the target was not found or was ambiguous. Run dsp search <text> --in <shortId> or dsp read <shortId> and choose a passage that occurs exactly once.

dsp edit says the version changed. Another update was published after your baseline. Read or search the version named in the error, reconcile the change, then retry with that version in --base-version.

Source read, search, or edit reports unsupported UTF-8. Export the original bytes with dsp export <shortId>, convert the file to UTF-8, then publish the corrected complete source.

An update (dsp publish --id <shortId> --base-version <currentVersion>) succeeded but an open tab still shows the old content. Remove any /_v/<number> suffix from the URL, then refresh the page. The version shown in the Display.dev bar should match the version printed by the CLI.

Search and view

Search palette shows "Couldn't load search index." The search data did not load. Click Retry. If the error remains, refresh the page and try again.

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 support@display.dev 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).

Was this page helpful?