Troubleshooting

Find the symptom below, then the cause and the fix. If your problem is not here, the Live request log is the first place to look: it shows whether a request arrived and what answered it.

Starting the server

"Port 8080 is already in use. Pick another port."

Another program, or another Mock Studio project that is running, already uses that port.

• Select Project in the rail and change Port to a free number, such as 8081. The server must be stopped to change it.

• Or stop the other program. To see what holds the port on Linux:

  ss -ltnp | grep 8080

Remember to update the address in your app when the port changes.

"Could not start server"

This message is followed by the system's reason. A common cause is a port below 1024, which ordinary programs are not allowed to open on Linux. Choose a port from 1024 to 65535.

The Port field cannot be edited

The port can only change while the server is stopped. The field reads Stop server to change while it runs. Select Stop, change the port, then Start server.

Send is greyed out in the test bar

The server is stopped. Select Start server in the side panel, or click the Stopped pill at the top right.

Requests get the wrong answer

I get 404 with "No mock endpoint matched"

The mock received the request, but no enabled endpoint fits its method and path. Open Live and look at the row with the no match tag. Compare it with your endpoint:

• Path. /user is not /users. Fixed text is case-sensitive. A prefix such as /api/v1 must be in the endpoint path if your app sends it.
• Method. A POST to a GET endpoint does not match. Use ANY to accept every method.
• Enabled. A disabled endpoint is ignored. Check the Enabled switch.
• Segments. /users/:id matches /users/42 but not /users or /users/42/orders. Use /users/** to match deeper paths.

See Endpoints and paths.

The wrong endpoint answers

When several endpoints fit, the most specific path wins, and on a tie the one higher in the list. Two endpoints with the same method and path shape, such as /users/:id and /users/:userId, tie, so the lower one is never reached. An ANY endpoint also ties with a specific method on the same path. Change a path, disable one endpoint, or merge them into one with conditional rules.

Conditional rules always send the fallback

• equals is case-sensitive and compares the whole value. Admin is not admin.
• Body field (JSON path) needs the request body to be a JSON object. Check Request body in the Live details.
• All conditions on a response must match. Remove conditions one at a time to find the one that fails.
• An imported endpoint may use the header x-mock-response-name to choose a response. See Import from Postman.
• An endpoint imported from OpenAPI has no conditions at all until you add them. See Import OpenAPI or Swagger.

I always get 401 "Missing Authorization header"

The endpoint has Require an auth header turned on and the request does not send that header. Send the header with any non-empty value, or turn the switch off under Advanced settings, Authentication. See Auth, CORS and project settings.

A token appears in the response as typed, braces and all

Mock Studio leaves a token such as {{query.page}} untouched when it cannot fill it in. Causes:

• The name is misspelled: {{uuuid}}, {{faker.adress}}.
• The request has no such value: no page in the query string, no such field in the body.
• The request body is not a JSON object, so no {{body…}} token can be read.
• The prefix is not lower case: {{Params.id}} instead of {{params.id}}.
• The body type is Empty, or the token is in a global header. Tokens are filled in only in response bodies and response header values.
• The text came from a Postman import and is a Postman variable with no value in the collection.

See Dynamic templating.

The response body is not valid JSON in my app

• The body editor shows Invalid JSON: fix the line it reports. The server sends the body as it is.
• An unquoted token was left as typed, for example "page": {{query.page}} with no page in the request. Quote the token or make sure the value is always sent.
• The response has the Malformed body fault. Set Fault injection back to No fault.

Responses are slow, fail or never arrive

Delays and faults stay on until you turn them off.

• Look for an active tag on Advanced settings, and check Base delay (ms) and Random jitter (ms).
• Check Delay override (ms) and Fault injection on each response card. A fault shows as a tag on the card's header.
• Check Global delay (ms) under Project.
• In Live, notes that start with Fault: and a status of RST mean a fault was applied.

See Latency and faults.

My OPTIONS endpoint is never used

While Enable CORS is on, the server answers every OPTIONS request itself with 204. Turn CORS off under Project to let your own OPTIONS endpoint answer.

A web page cannot call the mock (CORS error in the browser console)

Check that Enable CORS is on under Project. If the page is served over https:// and it calls the mock at a plain http:// LAN address, the browser may block the call as mixed content regardless of CORS. Serve the page over http:// during development, or reach the mock through a tunnel's https:// address.

Other devices

My phone cannot reach the mock

Work through these in order:

1. Is the server running? The pill at the top right must read Running.

2. Are you using the LAN address? localhost on a phone means the phone. Use an address from Local network (LAN) in the Share section, or scan the QR code.

3. Is the phone on the same network? It must be on the same Wi-Fi as the computer, not on mobile data or a guest network.

4. Is the address http://, with the port? For example http://192.168.1.20:8080/health. Some phone browsers switch to https:// by themselves; type http:// in full.

5. Is a firewall blocking the port? Allow incoming connections on the mock's port. On Ubuntu with ufw:

   sudo ufw allow 8080/tcp

6. Does the network isolate devices? Some office, hotel and café networks stop devices from talking to each other. Use a phone hotspot or a home network, or a public tunnel.

To check from another computer on the same network:

curl -i http://192.168.1.20:8080/health

Any reply, even the mock's 404, shows the mock is reachable. If the request appears in Live, the network is fine and the problem is the path or method.

"No LAN address detected. Are you connected to a network?"

The computer has no network connection that other devices could use. Connect to Wi-Fi or a wired network, then open the Share section again.

An Android emulator cannot reach the mock

Use http://10.0.2.2: and the port, not localhost. Android also blocks plain http:// traffic in apps by default; your app may need to allow cleartext traffic for development builds.

Tunnels

"cloudflared is not installed" or "ngrok is not installed"

Mock Studio looks for the program on your system's PATH and did not find it.

• Install the program, check that cloudflared --version or ngrok version works in a terminal, then open the Share section again.
• If you installed Mock Studio as a snap, it cannot start tunnel programs at all. Install the .deb package, or run the tunnel yourself in a terminal: cloudflared tunnel --url http://127.0.0.1:8080 or ngrok http 8080.

"ngrok did not report a public URL. Is your authtoken set?"

ngrok started but gave no address within about ten seconds. Save your token once, then try again:

ngrok config add-authtoken <token>

The tunnel shows Error, or "cloudflared exited"

The tunnel program stopped. Check your internet connection and start the tunnel again. A cloudflared quick tunnel gets a new random address each time, so give the caller the new address.

The tunnel stopped by itself

Stopping or restarting the server also stops a tunnel that points at it. Only one tunnel runs at a time. Start the server, then Start public tunnel again.

Proxy and import

Proxied requests return 502 "proxy_failed"

The real API in Forward unmatched requests to (base URL) could not be reached within 30 seconds. Check the address, including https://, and that the real API is up. The reason is in the reply's message field.

A recorded endpoint only answers one URL

A recording keeps the exact path, such as /users/42. Change the path to /users/:id. See Proxy and record.

A Postman or OpenAPI file is rejected

The message says why. Common cases: an environment file was picked in place of a collection, the file is not valid JSON or YAML, or the document has no paths. See Import from Postman and Import OpenAPI or Swagger.

Imported endpoints all return 404 from my app

Your app probably sends a prefix that was part of the collection's base URL, such as /api/v1. The Live section shows the path the app really sends. Add the prefix to the endpoint paths.

Projects and files

A project is missing after a restart

Mock Studio loads every .json file in the projects folder when it starts and skips files it cannot read. If you edited a file by hand, check that it is still valid JSON. Use Copy projects folder path in Settings to find the folder.

My hand edits to a project file were lost

The app writes the whole file on every change and reads files only at startup. Close Mock Studio before editing a project file or running git pull in the projects folder. See Projects, files and Git.

The sample project did not come back after I deleted it

The sample project is created once, the first time the app opens. To start again, create a project and add endpoints from the templates under +.

I deleted an endpoint by mistake

There is no undo, and deleting an endpoint has no confirmation. If the project is in Git or you exported it earlier, restore the file while Mock Studio is closed, or import the exported copy.

The Live log is empty after reopening the app

The log is kept in memory only and is cleared when you quit. It also keeps only the latest 500 requests per project.

Still stuck

Open an issue on the GitHub issues page. Include your Mock Studio version from Settings, About Mock Studio, how you installed it (.deb or snap), and the steps that lead to the problem. Remove secrets from anything you paste.

Next steps

• Quick reference
• Live request log
• Share on LAN or the internet