Troubleshooting
OAuth opens a blank page on macOS
Safari can silently block the redirect to the local http://127.0.0.1 callback. Set Chrome or Brave as the default browser, or paste an access token instead. Finish one attempt at a time: an abandoned attempt holds the callback port for a few minutes and can cause a "state mismatch".
A client says the gateway "was not found"
Only when running from source. Build the gateway once with npm run build:gateway. npm run tauri dev does not build this separate binary; packaged releases bundle it.
An npx/uvx server shows "Error", then works on retry
On a cold npm or PyPI cache the first connect can take up to about 2 minutes. v1.6.0+ shows Installing… during the wait. If it still fails, check network access and click Re-check.
"could not read/store secret" on Linux
Secret storage uses the freedesktop Secret Service (GNOME Keyring, KWallet or similar). Run Toolport in a desktop session, or install and unlock a keyring such as gnome-keyring.
Repeated macOS keychain prompts in dev
Unsigned dev builds get an unstable signing identity, so the keychain re-prompts. Signed releases (v0.9.3+) share a keychain access group with the gateway and do not prompt.
VS Code does not start the toolport server
VS Code may need you to click Start Server on the toolport entry the first time. After that it reconnects on its own.
Linux AppImage shows no window or a grey one
Fixed in 1.16.0; update. Older AppImages bundled wayland client libraries that broke Mesa EGL (EGL_BAD_PARAMETER).
Tools do not fire in Open WebUI
Set Function Calling to Native in the chat's Advanced Params. See Open WebUI.
Still stuck? Ask in the Toolport Discord or open a GitHub issue.