Troubleshooting
Find the message you see, read the cause and apply the fix. Messages are quoted as the app shows them; … stands for details that change.
TIP
Open the Console from the icon rail before you dig in. It shows every request as it went on the wire, redirects included, which often explains the problem at once. See Console.
Sending a request
"Request URL is empty." or "Invalid URL: …"
The URL field is empty, or what is in it is not a valid address after variables are filled in.
- Type the full address, for example
https://api.example.com/users. - If the URL uses a variable such as
{{baseUrl}}, check that an environment is selected and that the variable has a value. See Variables.
"Connection failed: …"
The app could not reach the server. The text after the colon comes from your system and names the reason.
| The details mention | Cause | Fix |
|---|---|---|
| Failed host lookup | DNS: the host name could not be found. | Check the spelling of the host. Check that you are online, and on the VPN if the host is internal. |
| Connection refused | Nothing is listening at that address and port. | Start the server. Check the port, and http against https. |
| Network is unreachable | No route to the server. | Check your network connection, VPN and proxy settings. |
"Connection timed out (30 s). Check the host and your network."
The server did not accept the connection in time. The number is your Connect timeout (s).
- Check the host and port. A firewall that silently drops traffic looks like this.
- If the network needs a proxy, set it up. See Proxy and certificates.
"The server took too long to respond (60 s)."
The connection was made, but the answer did not arrive in time.
- For one slow endpoint, raise Timeout (ms) on the request's Settings tab.
- For everything, raise Response timeout (s) in Settings.
See Per-request settings.
"Request cancelled."
You selected Cancel while the request was running. Send again when ready.
"Stopped after 10 redirects (the maximum)."
The server kept redirecting. It may be redirecting in a loop.
- Open the Console to see each hop.
- If the chain is expected, raise Maximum redirects on the request's Settings tab.
- To look at the first redirect itself, set Follow redirects to Off.
"Form file not found: …" or "Body file not found: …"
A form-data file field or a binary body points at a file that is not at that path. This is common after importing a collection made on another computer.
Choose the file again on the Body tab. If you use the Snap package, also read the section on Snap file access.
TLS and certificates
"TLS certificate could not be verified: …"
The server's certificate is not trusted. Typical causes are a self-signed certificate on a local server, a private company CA, or an expired certificate.
- Private or company CA: add the CA certificate under Settings, Proxy and certificates.
- Your own local server: set Verify TLS certificates to Off on that request's Settings tab.
- A public site: do not turn the check off. Check the address, and check your computer's date and time.
"TLS handshake failed: …"
The secure connection could not be set up. The app adds a hint when it can tell why:
- A hint about a private CA means the certificate is not trusted. Fix it as in the section above.
- A hint about a client certificate means the server wants you to present one. Add a client certificate for that host under Settings, Proxy and certificates.
"The https server closed the connection without answering (…)."
Servers that require a client certificate do this when none was sent. Add a client certificate for that host. See Proxy and certificates.
Messages about certificate files
| Message | Fix |
|---|---|
| "The CA certificate file was not found: …" | The file was moved or deleted. Choose it again, or clear the field. |
| "The CA certificate file is not a PEM certificate: …" | Use a .pem or .crt file in PEM text format. |
| "The client certificate for … has no certificate file." | Edit the entry and choose a PEM certificate or a PFX/P12 file. |
| "No private key was given for the client certificate …" | Choose the key file, or use a file that holds both the certificate and the key. |
| "The private key is encrypted; enter its passphrase: …" | Edit the entry and type the passphrase. |
| "The passphrase for the private key is wrong: …" | Correct the passphrase. |
| "The private key does not belong to the certificate (…)." | Choose the key that was created with that certificate. |
Proxy
"The proxy asked for credentials (407)."
Check the proxy username and password under Settings, Proxy and certificates.
"The proxy would not open a tunnel to the server (…)."
The proxy refused to connect to that destination. Check the address. If the host is on your own network and should not go through the proxy, add it to the Bypass list.
"The proxy port … is not valid."
Use a number from 1 to 65535.
"The proxy username or password has characters that HTTP/1.1 requests cannot send"
The login contains a ;, a : in the user name, spaces at either end, or an empty password. Change the credentials, or switch HTTP version to HTTP/2.
Requests do not use my system proxy
With System selected, the app reads the HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables it was started with. If none were set where the app started, requests connect directly. Set the variables and restart the app, or choose Custom and type the proxy in.
HTTP/3
"HTTP/3 on this platform uses the system curl, but yours has no HTTP3 support (…)."
On Linux and Windows, HTTP/3 requests are sent by the curl program on your system. The message shows the version it found, or "curl not found on PATH" when there is none.
- Install a curl built with HTTP/3. The message asks for version 8.6 or newer, built with ngtcp2 and nghttp3. Run
curl --versionand look forHTTP3on the Features line. - Or open Settings and switch HTTP version to HTTP/2.
With the Snap package, the app can only use a curl it can see from inside its sandbox. If the message says curl was not found although you have one installed, use HTTP/2, or install the .deb or tarball.
Other messages while HTTP/3 is selected
On Linux and Windows these come from curl:
| Message | Meaning |
|---|---|
| "Could not resolve host." | DNS: the host name could not be found. |
| "Connection refused — is the server up?" | Nothing is listening at that address and port. |
| "Request timed out." | No answer within the connect and response timeouts. |
| "TLS certificate could not be verified." | See TLS and certificates. |
| "curl transport failed: …" or "curl exited with code …" | curl itself failed. Try HTTP/2 to see whether the problem is specific to HTTP/3. |
The response bar does not say HTTP/3
HTTP/3 falls back to HTTP/2 or HTTP/1.1 when a server does not offer it. The response bar shows the version that was really used. On Android, requests that need a custom proxy, an extra CA, a client certificate or have certificate checks off are sent over HTTP/1.1. See App settings.
File access
The Snap package cannot read a file
The Snap package runs in a sandbox. It can read files in your home folder and on removable media only. A body file, certificate or .proto file anywhere else, such as /etc or /opt, is reported as not found.
Copy the file into a regular folder inside your home folder, such as
Documents, and choose it again. Hidden folders, whose names start with a dot, are not readable either.For a USB drive or another disk, the snap needs the removable media permission. Connect it once in a terminal:
bashsudo snap connect apiworkbench:removable-mediaIf you need files from other locations, install the
.debor tarball, which has no sandbox. See Install.
The same limit applies to the command-line runner in the snap, apiworkbench.cli.
A request worked on another computer but not here
Binary bodies, form-data file fields, certificates and .proto files are stored as paths, not as copies. Choose the files again on this computer.
Import and export
| Message | Cause and fix |
|---|---|
| "The file is not valid JSON." | The file is cut off or damaged. Export it again from the source tool. |
| "Not a supported file. Use an OpenAPI or Swagger spec (JSON or YAML), a HAR capture, a Postman collection or environment, or an ApiWorkbench workspace." | The file is some other format. |
| "Not a Postman collection, environment or globals file, nor an ApiWorkbench workspace." | The JSON is valid but is none of the supported kinds. |
| "The file has nothing to import." | The file holds no requests. |
| "OpenAPI … is not supported (3.x only)." or "Swagger … is not supported (2.0 only)." | Convert the document to OpenAPI 3.x or Swagger 2.0. |
| "The document has no operations under "paths" to import." | The OpenAPI document describes no endpoints. |
| "Nothing to import: everything in the capture was a static asset (images, fonts, CSS, JS)." | Turn off Skip static assets to import them, or record the capture again while the page calls its API. |
| "This export uses format v…; this app understands up to v1. Update ApiWorkbench." | The workspace file was made by a newer version. Update the app. |
| "Could not parse that cURL command." | The text must start with curl and contain a URL. See cURL in and out. |
| "Nothing to export yet. Save a request or create an environment first." | There is nothing in the workspace to export. |
Ctrl+S says "Use Save… above the URL to choose a collection."
The tab was never saved, so there is no collection to save it into. Select Save… above the URL and pick a collection. After that, Ctrl + S works.
WebSocket, Socket.IO, MQTT, SSE and gRPC
"Connect first, then send a message."
Messages can only be sent while the connection is open. Select Connect and wait for Connected. The same applies to Emit on a Socket.IO tab and Publish on an MQTT tab.
"WebSocket URLs start with ws://, wss:// (found …)."
The address uses a scheme the tab cannot connect to. Use ws:// or wss://. Server-Sent Events tabs need http:// or https://.
"No answer within 20 s" or "Could not connect: …"
The server did not complete the connection. Check the address and the port, and whether the server needs wss:// in place of ws://. The log shows the system's reason after "Could not connect".
"Gave up after 5 reconnect attempts"
Automatic reconnecting reached its limit. Fix the cause, then select Connect again. Change Attempts on the Settings tab if you want more, or 0 to keep trying.
Socket.IO connects but nothing happens
- The server must speak Socket.IO protocol 4 (server versions 3 and 4). Version 2 servers are not supported.
- A path after the host is the namespace. If your server uses a custom handshake path, set it under Handshake, not in the URL.
- With Catch-all off, only the events switched on under Listen are logged.
MQTT: "The broker URL starts with "…😕/"."
Use tcp:// or mqtt:// for plain connections, ssl:// or mqtts:// for TLS, or ws:// and wss:// for brokers that speak MQTT over WebSocket.
MQTT: the connection drops as soon as another client connects
Two clients with the same Client ID push each other off. Clear the field to get a random id for every connection.
SSE: "The server answered 401 …"
The stream address refused the request. The log shows the status and the start of the response. Add the missing header or token on the Headers tab. A response other than 200 is never retried.
gRPC: "Could not load services"
The app could not get the service list.
- Check the address and the Use TLS switch. A plaintext server with TLS on, or the reverse, fails.
- The server may have reflection turned off. Select Import .proto files and add the
.protofiles.
gRPC: "Add .proto files or paste a .proto definition in the Proto tab first."
Import .proto files is selected, but nothing has been added yet. Open the Proto tab and add files or paste a definition.
gRPC: "The message does not fit …"
The JSON in the Message tab does not match the request type. Select Generate example message to see every field with the right shape. Remember that 64-bit numbers are written as strings and enum values by name.
gRPC: the call ends with 14 UNAVAILABLE
The server could not be reached, or dropped the connection. Check the address and the TLS setting. See gRPC for the other statuses.
Still stuck?
Report the problem on the app's GitHub issues page. Include:
- The ApiWorkbench version, your operating system and how you installed the app (Snap,
.deb, zip, APK). - The exact message, and the steps that lead to it.
- What the Console shows for the request.
DANGER
Remove tokens, passwords, cookies and private addresses before you post anything. Issues are public.