Troubleshooting and FAQ

Fixes for the problems people run into most, and short answers to common questions. If yours isn't here, ask in Discussions or open an issue.

Installing

Windows says "Windows protected your PC"

The Windows installer isn't code-signed yet, so SmartScreen warns about it and calls the publisher unknown. Click More info, then Run anyway.

To check the file first, compare its hash with SHA256SUMS.txt on the releases page. In PowerShell:

Get-FileHash .\spec0-studio-windows-x64-setup.exe

macOS warns that the app can't be checked

It shouldn't: the Mac app is signed and notarized by Apple. A warning means something is wrong with the download. Don't open it; check it against SHA256SUMS.txt, as described in Install, and download it again if it doesn't match.

Studio won't start on Linux

Studio needs WebKitGTK 4.1: Ubuntu 22.04, Debian 12 or newer, or another distribution of about that age. Builds are x86_64 only. If an AppImage won't run, check that it's executable (chmod +x).

Specs

My Swagger 2.0 spec looks different

Studio converts Swagger 2.0 to OpenAPI 3.0 when you open it. The Raw tab shows the original file; everything else uses the converted spec. Where the conversion may not be exact, such as a tsv list format, Studio says so. See Swagger 2.0 specs.

Swagger 1.2 and older don't open.

A $ref to another file doesn't resolve

Studio doesn't follow references to other files or URLs. Bundle the spec into one file first, for example with npx @redocly/cli bundle openapi.yaml -o bundled.yaml.

I edited the spec file, but Studio shows the old version

Studio works from its own copy of the spec. Press Refresh on the API's card in the library to re-read it. See What Studio keeps.

The request goes to the wrong server, or to a path like /api/v3

The base URL is yours to set: type it in the address bar, or pick a server from the target menu. A spec from a local file whose server is a path (such as /api/v3) has nothing to resolve it against, so type the full address. See The address bar.

Networks

Requests fail behind a corporate proxy

Studio uses HTTPS_PROXY, HTTP_PROXY and NO_PROXY from your environment. If Studio was started from somewhere those aren't set, such as the Dock, set the proxy in Settings → Network. See Proxy.

"Certificate" or "unknown issuer" errors

The server's certificate comes from a CA your system doesn't trust, which is common for internal APIs. In Settings → Network, trust the CA's PEM bundle for that host. Skipping verification also works, but only use it when you have no bundle. See Certificates.

Check for Updates fails at work

The update check uses Studio's proxy setting, but not its certificate settings. If your network inspects encrypted traffic, the check can fail. Download the new version from the releases page instead.

Secrets

Secrets aren't in the keyring on Linux

Studio keeps secret values in the Secret Service. With no keyring running, or a locked one, it falls back to a local file that isn't encrypted, and the Environments dialog says so. Install or unlock a keyring such as GNOME Keyring or KWallet, then restart Studio: the values move into it.

This also happens in a session with no desktop.

A long token won't save on Windows

Windows limits how long a stored credential can be. A token over that limit stays in Studio's local file instead, and the Environments dialog says how many values that affects.

Ports

The local mock didn't start on port 4010

Another program is using it. Studio uses the next free port, up to 4099, and shows the one it picked. An API keeps its port the next time. If every port from 4010 to 4099 is taken, stop another local mock or free a port.

The MCP server started on a different port

Port 47321 was taken, so Studio used the next free one and told you. Copy the setup text from the MCP tab again: it has the new address. You can also choose a port in the MCP tab.

Collections

A step says the local mock isn't running

Steps don't start mocks. Start the API's local mock, or pick another target in the step's Send to.

A step failed with a value that couldn't be found

A link couldn't be filled: the earlier step failed, didn't run, or its response didn't have that field. Open the run log to see which value, and the Chain view to fix the link.

A step is marked "changed"

Its spec changed since the step was made, and the step no longer matches it. The step says what changed. See When a spec changes.

Questions

Do I need a Spec0 account?

No. Only hosted mocks, your organisation's catalog, and publishing need one.

Does Studio send my data anywhere?

No. It sends no telemetry, and your history, environments, secrets and collections stay on your computer. See Privacy and security.

Can I run a collection from CI?

Not yet. Collections run in Studio only.

Does Studio run Postman scripts?

No. When you import from Postman, status checks and saved response values are converted; other scripts are listed, not run.

Is there support for GraphQL, gRPC or WebSockets?

Not yet. Studio is built around OpenAPI specs and HTTP requests.