Gadwal
Coming soon

Troubleshooting

Each problem with what you'll see and how to fix it. Most come down to Gadwal being closed, the server being off, or an old token.

Illustration: a plug about to meet a socket with a green check light, beside a magnifying glass over a grid tile.

First checks

  1. Gadwal is open. The server runs inside the app.
  2. The server is on. The AI & MCP entry in the sidebar (⌘2) says Running, not Off or Couldn’t start.
  3. The app’s row says Connected. “Token issued · no calls yet” means the app has a token but hasn’t called; “Not connected” means it was never set up.
  4. Ask AI Activity. Every call that reached Gadwal is there with its result. If nothing is logged, the request never arrived.

You can also test the server from Terminal with the app’s token (from ⋯ › Show Token). A JSON answer means the server and token work:

curl -s http://127.0.0.1:55183/mcp \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

The app can’t reach Gadwal

You see: “connection refused”, “failed to connect”, the server listed as failed or disconnected, or in Claude Desktop: “Gadwal is not running, or its MCP server is off”.

Fix: open Gadwal and turn on MCP server on the AI & MCP page. Then restart the AI app or reconnect the server (in Claude Code, /mcp). If you changed the port, set the app up again so it gets the new address.

Port in use, or “Couldn’t start”

You see: the AI & MCP entry says Couldn’t start, and the Status line reads “The MCP port couldn’t be opened: … Another app may be using it.”

Fix: type another port in Port (1024 to 65535) and press Return. The address changes, so press each app’s button again (Install, Copy Command and so on) to send it the new one. To see what holds the port:

lsof -nP -iTCP:55183 -sTCP:LISTEN

If the status says “The MCP server stopped: …”, turn the server off and on again.

401 Unauthorized

You see: “Missing or invalid bearer token.”, “unauthorized”, or in Claude Desktop: “Gadwal rejected this extension’s token”.

Why: the token was rotated or revoked, the app was set up before a reinstall, or the header was lost when you pasted it.

Fix: press the app’s button on the AI & MCP page again (Reinstall, Copy Command, Copy config.toml Block or Copy JSON) and redo its setup. For Claude Code, remove the old entry first:

claude mcp remove --scope user gadwal

The header must be exactly Authorization: Bearer <token>.

403 Forbidden

You see: “Requests from web pages aren’t accepted.”

Why: the request carried an Origin header or browser fetch metadata, which only web pages send. Gadwal refuses these on purpose, so no website can reach your databases.

Fix: connect from a desktop MCP client (Claude Desktop, Claude Code, Cursor, VS Code, Codex). Browser-based tools and web connectors can’t be used. If you’re writing your own client, don’t send Origin.

A 421 (“This server only answers on 127.0.0.1:…”) means the request used another host name: use http://127.0.0.1:55183/mcp exactly, not your Mac’s name or IP address.

ChatGPT.com or Claude.ai can’t connect

They run in the cloud and can’t reach 127.0.0.1 on your Mac, by design. Use Codex (for OpenAI) or Claude Desktop or Claude Code.

A database connection is unreachable

You see: a tool fails with the database’s own error (timeout, host not found, authentication failed, SSH tunnel failed).

Fix: the AI uses the same saved connection you do. Open it in Gadwal and check it connects: VPN on, SSH key available, password still valid, database up. Once it opens in Gadwal, ask the AI to try again.

“No connection … is available to AI”

The connection’s AI level is Off, or the name doesn’t match. Ask the AI to call list_connections, or raise the level in the connection’s AI access. If two connections share a name, the AI must use the id.

“This connection is read-only for AI”

You see: “This connection is read-only for AI, so write statements aren’t run. Ask the user to raise its AI level in Gadwal.”

Why: the connection is at Read-only, which is where Production starts.

Fix: that’s working as intended for production data. To let the AI propose changes, set AI access to Ask before write (Production asks you to confirm). Its writes then wait for you in Review.

Similar refusals:

  • “This statement changes data …; run_query only reads.” The AI should use execute_sql instead.
  • “… is hidden from AI on this connection.” The column is hidden; that’s on purpose.
  • “Gadwal’s AI tools need the lifetime unlock (or an active trial)”: the trial ended. Unlock Gadwal to use AI tools.

A change never ran

  • It’s still pending: open Review from the AI pill in the toolbar.
  • It expired: nobody decided within 24 hours. Ask the AI to propose it again.
  • It failed because a row changed after it was proposed: the AI should read the row again and propose a new change.
  • Its status is unknown: the connection to the database dropped while it was saving, so it may or may not have run. Check the data in Gadwal before you ask the AI to try again.
  • The AI stopped waiting: wait_for_change waits 120 seconds at most. Ask it to check get_change_status.

Session not found

Sessions close after 30 minutes without a request, and when Gadwal quits or a token is rotated. Most clients start a new session by themselves; if yours doesn’t, restart it or reconnect the server.

Too many requests (429)

Each app may send about 20 requests a second. After several bad tokens in a row, Gadwal also slows that address down for a few seconds. Wait and retry.

Still stuck?

Email support@gadwal.dev with the AI app’s name and version and the error text. Never send your token.