Troubleshooting

macOS says the app could not be verified

Release builds are not notarized, so Gatekeeper blocks a file you downloaded in a browser. Do one of these:

• Remove the quarantine flag: xattr -dr com.apple.quarantine /Applications/Postguy.app.
• Open System Settings → Privacy & Security and choose Open Anyway.
• Download with curl and unpack with ditto, which never sets the flag. The commands are on Installation.

Windows shows "Windows protected your PC"

The installer is not signed, so SmartScreen warns you.

1. Choose More info.
2. Choose Run anyway.

To be sure of the file, check it against SHA256SUMS.txt first. See Installation.

"workspace already open by pid …"

A workspace can be open in only one process at a time. Opening it takes a lock file at <workspace>/.postguy/lock. The file holds the process id and a start time. The full message is:

workspace already open by pid 1234; close that instance or remove <workspace>/.postguy/lock if it is gone

1. Close the other Postguy window, or stop the postguy-cli command that has the workspace open.
2. If Postguy crashed, start it again. A lock is taken over automatically when its process no longer exists or the lock is older than three minutes.
3. If a process was killed and the message persists, delete the lock file by hand.

A file was corrupt

Postguy never silently drops or repairs a data file.

• If a document, settings or session file can't be read, Postguy renames it next to the original as <name>.corrupt-<time>. The app starts with a default in its place and shows a note (for settings: "settings file corrupt; moved to …").
• A .corrupt-<time> file is kept for you to inspect or repair. Postguy does not read it again.
• Every save is atomic. The previous version is kept as <name>.bak, one generation deep.

To go back to the previous version:

1. Close Postguy.
2. Copy the .bak file over the file.

See Workspace and Workspace format.

TLS or certificate errors

Requests fail behind a proxy

By default Postguy uses the system proxy settings. It reads the HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY environment variables (upper or lower case).

• A graphical launcher may not pass your shell's variables to the app. Start Postguy from a terminal to test.
• Or set Proxy mode to Custom proxy in Settings → Proxy. A custom proxy wins over the environment.
• The Console logs the proxy a request actually used.

Details: Cookies, proxy and certificates.

File dialogs do not open on Linux or FreeBSD

Open and Save dialogs use xdg-desktop-portal.

• Install it and a backend that matches your desktop.
• The .deb lists xdg-desktop-portal as a recommended package.
• In the Flatpak build, dialogs always go through the portal because the sandbox has no filesystem access.

The window does not start on Linux

Postguy loads X11 or Wayland, xkbcommon and EGL/GL libraries at run time.

1. Check that the libraries listed under Linux on Installation are installed.
2. Start the app from a terminal so you can see any error message.

Scripts do nothing

1. Open Settings → General and check that Disable scripts is off. When it is on, pre-request and post-response scripts are skipped for every request and run.
2. Remember that scripts run only for HTTP requests, not gRPC or WebSocket.

See Scripts and tests.

Where to look for diagnostics

Postguy writes no log file. Look here instead:

• Console: click Console at the bottom left, or press Cmd/Ctrl+Alt+C. It lists request summaries, logs, warnings and errors. Script console.log output appears here. Filters: All, Requests, Logs, Warnings, Errors.
• Status line: the text at the bottom right of the window shows the result of the last action ("Ready", "Created request", and error messages).
• Import report: after an import, the report lists what was changed, skipped or unsupported.
• Terminal: messages that can't be shown in the window, such as "control channel disabled", go to standard error. Start the app from a terminal to see them.
• CLI: postguy-cli prints errors to standard error. It exits 1 for a failure and 2 for a usage error. See the CLI reference.

If none of this helps, open an issue at github.com/zuramai/postguy/issues. Never paste real tokens, API keys or private responses.