Most problems in 1DesignTool come down to a handful of causes — a missing or signed-out agent, a run that stalls, a preview that won't render, a gate FAIL, or a spent cap. This page is the first place to look for each.
The agent isn't in the picker
The app finds supported CLIs on your PATH — same way a terminal does.
- Is it installed? Run the CLI by name in a terminal (
claude,codex…) — if the shell finds it, the app should too. - Is it signed in? The picker shows sign-in state; a missing sign-in is the CLI's own auth, not the app's. Sign in on the CLI's side and reopen.
- Is it on the roster? The 16 supported CLIs are listed at Supported coding agents — a CLI not on the list can't be plugged in.
A run stalls or fails
- Check the agent's quota — turns bill to your CLI's account; a spent or lapsed account fails the run visibly in the transcript.
- Read the transcript — the agent's own output is there; a CLI-side error shows up as itself, not as a generic failure.
- Retry once — a transient CLI failure sometimes lands on retry. A failure that persists has a cause the transcript names.
The preview won't render
- The preview is default-deny — a file type the classifier doesn't serve renders as nothing rather than unsafe. This is the safety floor, not a bug.
- A stale worktree — on a codebase project, the preview reads the
1design/<slug>worktree; if the branch state looks odd, review the branch bar's diff before suspecting the render. - Refresh the panel — the reload button on the preview rail re-reads the folder; a half-written file usually clears on the next paint.
A gate FAIL won't clear
- Fix at this width — a FAIL finding's fix button sends exactly that issue back to the agent as a one-line brief; the finding names the width and the element, so the fix is usually mechanical.
- Check it at that width — the finding says which viewport broke; look at the result there before assuming the rule's wrong.
- Some findings are deliberate — a known trade-off can be accepted; the gate advises, it doesn't block. See The design-kit gate.
A cap refuses a run
A 1design:limit: refusal names the spent cap — turns, renders, versions,
variants or design systems on the free tier. Settings → Usage shows the
meters in full, and archiving a version frees a slot without a license. The
caps are lifetime counters; Pro removes them. See
Free vs Pro.
On Windows: EISDIR errors (known issue)
In 1.7.0 on Windows, the design-kit scripts can fail with EISDIR — which
breaks Knowledge, post-turn checks, video export and Build mode. It's a known
bug, fixed in the next release; on macOS the same flows are unaffected.
An MCP client won't connect
- Check the access panel — Settings → MCP access shows the endpoint, the token, and the allowed-client list; a refused client usually isn't on the list.
- Check the token — the panel's token is what the client sends; a stale or wrong token refuses the connection.
- Check the activity log — the log shows what reached the server and what didn't.
Where to look first
- Transcript panel — the agent's output, verbatim
- Branch bar — on a codebase project, what the turn actually changed
- Settings → Usage — which meter is spent
- Activity log — what an MCP client actually did
Tip: The transcript is the first read, always — the agent's own output is the honest version of what happened, and most "the app broke" cases are really "the CLI said something the UI translated too softly".