Reference
Troubleshooting
The common snags, in the order you're likely to hit them. Most connection problems come down to one question: where is the client finding (or not finding) your server address and license key?
Connection failures
SQUAT doesn't connect at all
- Check both settings are actually set. The launcher needs a server URL and a license key — from
SQUAT_SERVER_URL/SQUAT_LICENSE_KEYenvironment variables, or from~/.squat/config.json. If neither source yields both, the connection simply won't start (the launcher prints a setup message to its error log and exits). - Remember the resolution order. Environment variables win over the config file, field by field. A stale env var will silently override a corrected config file.
- Restart the client after any change — clients read these settings at launch, not live. Desktop apps launch without your shell environment, so env vars set in a terminal don't reach them; use the config file there.
- Verify by asking your AI to check the SQUAT workspace connection. A successful workspace identity/member response means connected.
SQUAT tools missing in the Claude app / the server keeps disconnecting
You installed the plugin, but no SQUAT tools appear — or the server cycles between “connecting” and “disconnected.” The current plugin manifest selects a remote OAuth connector, not the stdio launcher. Start a new session and complete connector authorization. If you manually selected the alternate .mcp.stdio.json in a sandboxed app (Cowork especially), it may be unable to read ~/.squat/config.json or shell variables; switch that client to the remote connector instead of debugging the inaccessible file.
The fix is the connector. Add SQUAT as a custom connector and sign in once in the browser; the app then holds its own pass and needs no file at all. See Connect from the Claude app. Keep the plugin installed — it's still what provides the skills.
It fails silently
Turn on launcher diagnostics: set SQUAT_LAUNCHER_LOG=~/.squat/launcher.log in the launcher's environment, retry, and read the log. Your client's own MCP log (most clients have one) is the other place the story gets told.
If you know the job but not the tool name, ask the client in plain language: “use SQUAT concierge to help me recover this operation”, “use SQUAT maintain to check workspace health”, or “use SQUAT review to show the project ledger.” When the host offers MCP prompts, choose the matching prompt; squat_help is the fallback for hosts that expose neither prompts nor plugin skills.
Checking whether the server is up
Hosted servers answer a simple liveness check at /health:
curl -s https://api.squat.pro/healthIf your organization runs its own SQUAT server, use its address instead.
Use /health, not /healthz, on a hosted URL. Some cloud frontends reserve paths ending in “z” and return their own branded 404 before the request ever reaches SQUAT — so a 404 on /healthz with a healthy service is a red herring, not an outage. (/healthz does work against a locally-run server.) The health response is deliberately minimal — { "ok": true } and nothing more.
License key problems
| Symptom | Likely cause & fix |
|---|---|
| “Set up your key” message; tools never appear | Key or server URL missing from both the environment and ~/.squat/config.json. Fill in one of the two paths and restart. |
| Key rejected | Check for copy/paste truncation (keys start with sqk_), and that the key hasn't been revoked or replaced. Manage keys from your account page at www.squat.pro/account. |
| Raw license key was lost | SQUAT cannot recover the raw key. Ask your account operator for a replacement, confirm it connects, and revoke the lost credential. Your workspace data remains intact. |
| Device limit reached | A key works on three active devices. Free a slot from the Devices page of your account (www.squat.pro/account/devices), add a device pack for three more, or set up a shared project device for a CI repo, which counts as one slot for the whole team. |
| “Squad is full” when saving a persona | You're on Starter, which holds three squad members. Retire one you no longer need, or move up a tier — Solo holds 24. SQUAT offers the options rather than failing silently. (A separate limit governs the learning slot: one member on Starter keeps learnings between rounds, and you can move it whenever you like.) |
| Key was committed to a repo or pasted publicly | Treat it as exposed: issue a replacement, confirm it connects, and revoke the exposed credential through your account/operator. This changes access credentials, not workspace data. Never store the key in project config files that get committed (looking at you, config.toml). |
Which version am I actually running?
Ask for your workspace info — the reply now names the server version and build that answered the call. Use that when you are recording what a round was tested against, rather than your own recollection of the last release note. If it comes back as unknown, the connection did not carry a build identity; say so rather than filling in a guess, because a round pins what you tell it and that record is permanent.
The same applies to issue counts. When you ask for the issue list you get a bounded page, and the reply now tells you the exact total alongside it. If those two numbers differ, report the total — the page length is not a count of your workspace.
Signing out, and what it does not do
Signing out in your client — codex mcp logout squat and its equivalents — removes the credential your client had stored. That is a local action. It does not, by itself, tell SQUAT to end the authorization, and a task that is already running may keep working with the credential it is holding until that credential expires.
Clients that follow the standard revocation call end the authorization properly, and SQUAT now retires a credential pair together rather than half of it — so a session that has refreshed at any point no longer leaves a second, forgotten credential alive behind it. But if your client only clears its own storage, the authorization on our side is still valid.
| What you want | What to do |
|---|---|
| Sign out on this machine | Your client's own logout. Then close any task that was already running — that is the part local logout cannot reach. |
| End every session for a person, everywhere | Ask your account operator or administrator to revoke that user's authorization. This ends existing sessions rather than waiting for them to expire. |
| You believe a credential is compromised | Revoke it, don't just sign out. Treat it the way you would an exposed license key — issue a replacement, confirm it connects, then revoke the old one. |
If you are switching between workspaces for testing, sign out and restart the client before starting the new run. A round is written to whichever workspace your session is bound to, and the round receipt now names that workspace — check it before you continue, rather than discovering it later.
LM Studio quirks
| Symptom | Fix |
|---|---|
MODULE_NOT_FOUND on startup | The args entry in mcp.json contains a URL. It must be the local file path to the launcher script; the server URL goes in SQUAT_SERVER_URL. See Setup. |
| Model says “I can't receive or process files” or won't use tools | Some local models need a nudge. Give the model a short system prompt telling it that it operates SQUAT through the connected tools directly — your operator's setup guide includes ready-made fallback text — or start with an explicit instruction: “Use the squat tools: check the workspace connection first.” |
| Imported personas come out mangled or fragmented | Don't attach large persona files to LM Studio retrieval. Use the folder staging path to preserve IDs, then complete each file through the governed recruiting flow (source, communication range, audition, activation). Staging alone is intentionally pending and cannot run. See Importing. |
| Everything passes, personas feel flat | Small models produce flat personas and generous grading. Use a stronger instruction-following model for interviews and evaluation — or route the evaluator to a stronger model via a model policy. The ledger records which model ran, so you can see exactly when grading quality changed. |
| A wave of failures after switching models | Check the failure classes before blaming your app: a burst of agent-class failures usually means the model, not the product. See Reviewing history. |
| Multi-model routing not working | The local completion path only activates when a local server is actually listening (default http://localhost:1234/v1). Enable LM Studio's local server, load the named models, or point SQUAT_LLM_BASE_URL at the right host/port. |
Rounds blocked by login
A round hits a login wall and stops — this is working as designed, not a bug:
- The persona will never type a password — the credential rule has no exceptions. The attempt is recorded as
blocked, classed as a harness or test-design problem, never an app failure. - The fix: inspect the scenario's non-secret authentication policy and prepare the session before acting — an allowed existing session, an approved local login helper when your operator has configured one, or direct operator entry while browser automation and capture are paused.
- If local setup still blocks: check the exact origin allowlist, scenario version/binding, UAT account state, and post-login check. Never paste a password into chat or a tool argument.
- A remote-only agent with no prepared/operator-controlled local browser must fail closed as
local-auth-required. Tighten the scenario or move the run local; do not weaken the credential boundary.
Round and review oddities
| Symptom | What's happening |
|---|---|
| A comparison between two rounds is refused | One of them is invalidated (the reason is surfaced — pick another baseline) or is a design panel round (nothing scored to compare). Deliberate, not broken. |
| A result marked Inconsistency | The result may be transient or unreliable. Re-run that pair before treating it as signal. |
| Results shifted but so did the model | Attribution question — check whether the tester's stack or your product's build changed. See Reviewing history. |
| A deploy landed mid-round | The round should be invalidated with a reason — a target change mid-session voids the run. Say so and SQUAT handles it. |
| A round will not complete because evidence is pending | Let SQUAT finish recording the canonical dialogue or finalizing the referenced attachment. A contract panel must resume, recover an already-authorized failed append, or be invalidated; only eligible non-panel rounds may use the separate approved evidence-gap path. |
| An import failed with “<persona/scenario> not found” | Historical rounds reference personas and scenarios that must exist first. Import those, then re-run the round import. See Importing. |
| A notice keeps appearing at session start | The active acknowledgment scope was left on remind me later, which brings it back every session. Say “dismiss it” and it does not return for the scope your client shows. See Setup & connection. |
Support cases from your assistant
You do not need the portal to work a support case. Ask your assistant to open a case (it files it and returns a reference like SQUAT-1023), to check a case by that reference, or to add to a case when you have more to say — your message is appended to the case for the support team, attributed to your workspace, and does not reopen a case that has been resolved or closed. Keep the message to what you saw in SQUAT; never paste protected workspace content into a case.
Index errors
If a query fails with an error mentioning a missing database index, that's a server-side setup gap, not something you can fix from your client: the server's database needs its index definitions deployed. On a hosted workspace, report it to your operator. If you're running the server yourself, deploy the index definitions that ship with the server and retry.
SQUAT support asked to see my data — what do I do?
That's a real, owner-controlled flow: support names the case and the exact records in the ticket, you tell your AI assistant in plain language to grant access, and you paste the returned grant ID — a safe, non-secret reference — back into the ticket. Support can then read only those fields, fully audited, until the grant expires (15 minutes to 7 days) or you revoke it. The full walkthrough is in Roles & security.
Real SQUAT support will only ever ask you to create a grant in your own client and share the grant ID. It will never ask for a password, license key, sign-in code, or any other secret — anyone who does is not SQUAT support. Decline, and report it to your operator.
Still stuck?
- Ask your AI to call SQUAT's help — a built-in orientation any connected model can fetch (
squat_help), useful when the AI itself seems confused about what to do next. - Gather the launcher log (
SQUAT_LAUNCHER_LOG), your client's MCP log, and what the health check returned — then contact your operator. Those three answer most questions on the first pass.