Troubleshooting
Start with doctor. It checks everything GUIJam needs and says what to fix:
npx guijam doctorTo also check that your AI tool answers a real request, add --probe. It sends one short request and spends a few tokens:
npx guijam doctor --probeBelow are the messages you might see, where they appear, and what to do.
Setup and doctor#
No gjd binary for your platform#
No gjd binary for
<platform>. GUIJam ships gjd for macOS and Linux (arm64, x64) and Windows (x64). Reinstall guijam, or set GUIJAM_GJD_BIN to a gjd binary.
The gjd daemon is installed as an optional dependency for your platform. Reinstall guijam so your package manager fetches it. If you install with optional dependencies turned off, turn them back on.
No package.json#
No package.json in
<folder>. Run this in your app's folder.
Run init from the folder that holds your app's package.json, or pass --cwd <dir>.
Node is too old#
Node
<version>is too old. GUIJam needs ^20.19.0 or >=22.12.0.
Upgrade Node. SolidStart 2 itself needs Node 24.
A config that can't be edited safely#
<file>can't be edited safely: its config is too indirect.
init edits your framework's config only when it can do so safely. When the config is built dynamically, it prints the lines to add instead. Add them by hand: see Manual installation. Other reasons include "it could not be parsed", "it has no default export" and "its default export is not a config object".
Next.js is too old#
GUIJam needs Next.js 16.3 or newer (this app has
<version>). Upgrade Next.js, then run init again.
Upgrade Next.js, then run npx guijam init again.
Unsupported framework#
GUIJam doesn't plug into Angular yet. Angular support is on the roadmap.
No Vite dev server found. GUIJam runs inside Vite for now.
GUIJam runs inside Vite-based dev servers and Next.js. SolidStart 1 runs on vinxi: upgrade to SolidStart 2. See Requirements.
Vite version warning#
Vite
<version>. GUIJam supports Vite 6, 7 and 8.
A warning, not a failure. Other versions may work, but aren't tested.
GUIJam isn't wired in#
guijam is not in package.json. Run npx guijam init.
<config>does not load guijam. Run npx guijam init.
Run npx guijam init, or follow Manual installation.
The toolbar is missing with vite-plugin-pwa#
vite-plugin-pwa runs a service worker in development. It can serve a cached page without the toolbar; if the toolbar is missing, clear the site data for this address in DevTools.
In Chrome DevTools, open Application, then Storage, and click Clear site data. Then reload.
Elements don't map to source#
GUIJam maps elements to source in React, Preact, Solid, Vue, Svelte and Astro.
<UI>elements won't map to source yet.
Elements rendered outside these libraries show on the page, but GUIJam can't edit their source yet.
AI tool problems#
No AI tool is ready#
No AI coding CLI is installed and logged in. Install
<names>.
<tool>is chosen but not installed. Install it with<command>
<tool>is not logged in. Run<command>.
Install your AI tool and log in with its own command, then try again. Each tool's page lists both: see AI tools. OpenCode counts as logged in only once it has at least one provider key. For Qwen Code and Gemini CLI, doctor shows the login status as unknown, because those tools have no status command. Run npx guijam doctor --probe to find out for sure.
The AI tool refused the request#
<tool>was refused:<what the tool said>.
<tool>isn't logged in.
Your AI tool turned the request down. The first message repeats its reason, such as an invalid or revoked key. The second appears when the tool gave no reason. Run the login command the message names, then retry. With OpenCode, add a key for the provider of the chosen model with opencode auth login, or pick another model with npx guijam init.
OpenCode was refused: Model access is disabled. Change model access at
<link>.
Your OpenCode account has this model turned off. Turn it on at that link, or pick another model with npx guijam init.
Gemini CLI was refused: Google no longer lets Gemini CLI use a personal Google login (IneligibleTierError)…
Gemini CLI needs an API key now. Set GEMINI_API_KEY where your dev server starts, choose it in Gemini CLI with gemini → /auth → Use Gemini API Key, then restart the dev server. See Gemini CLI.
Qwen Code was refused: Qwen OAuth free tier was discontinued on 2026-04-15…
Run qwen, choose /auth, and switch to a Qwen plan or a provider key. See Qwen Code.
<tool>can't reach<model>with the keys it has.
The model you saved belongs to a provider your AI tool has no key for anymore. Add a key for that provider, or pick another model with npx guijam init.
OpenCode is out of credit or on a free model#
OpenCode couldn't answer:
<what OpenCode said>. Add credit to the account behind this model, or pick another model with: npx guijam init.
The key works, but the account behind it is out of credit or has no billing details. Top it up, or pick another model.
OpenCode couldn't answer: Free usage limit reached. … OpenCode's free models only answer OpenCode's own agents, not tools like GUIJam.
OpenCode's own free models don't answer other tools, so init no longer lists them. Pick a model you have a key or plan for with npx guijam init. See OpenCode.
Rate limited, overloaded or no answer#
<tool>is rate limited. Retry in a minute.
<tool>is overloaded. Retry in a minute.
No answer within
<N>s.
Your AI tool's provider is busy, or the request took longer than its time limit. Retry, or simplify the prompt. See the time limits.
The tool stopped or couldn't answer#
<tool>stopped before answering:<the last line it printed>.
<tool>couldn't answer:<what the tool said>.
Your AI tool exited without an answer, or reported an error GUIJam has no specific advice for. The message repeats the tool's last line of explanation, skipping stack traces, which usually says why, such as "model not found". Fix what it names, then retry.
Every failed run is logged in .guijam/logs/gjd.log, with the tool, its version, the model and the full error. Account and session IDs in the error are replaced with redacted. Check it when a message isn't enough.
The answer wasn't valid edits#
The model's answer wasn't valid edits
The model answered in a shape GUIJam couldn't apply. Retry, or simplify the prompt.
The tool can't read images#
<tool>can't read images, so sketches and attached images need an AI tool that can.
Switch to a tool that reads images, such as Claude Code or Codex, with npx guijam provider use <id>. With OpenCode, pick an image-capable model with npx guijam init.
Links without screenshots#
No Chrome, Brave, Edge or Chromium was found, so links were read without screenshots. Set GUIJAM_BROWSER to a browser to add them.
Install a Chromium-based browser, or point GUIJAM_BROWSER at one. Set GUIJAM_BROWSER=off to turn link screenshots off.
In the widget#
Your edits conflict with this change#
Your edits to
<file>conflict with this change. Review them, then preview again.
You changed the file after the preview was made. GUIJam won't overwrite your work. Review your edits, then preview again.
The variant no longer fits#
This variant no longer fits
<file>: it changed after the drawing was made.
<file>changed since the AI read it.
Generate again, so your AI tool starts from your latest code.
Up to three drawings#
Up to 3 drawings at a time. Use or discard one first.
Finish one drawing with Use or Discard, or cancel one that's still generating.
Only Ask AI can change this element#
This className is computed at runtime, so it can only be changed with Ask AI.
The class comes from an expression GUIJam can't rewrite exactly. Click Ask AI and describe the change.
Protected paths#
<path>is on the deny-list
GUIJam never writes to .git, node_modules, dist, build, .guijam, .env files, or .pem and .key files, or anywhere outside your project.
The dev server isn't connected to the daemon#
The Vite dev server is not connected to the GUIJam daemon.
This dev server runs without the GUIJam daemon.
Restart the dev server. If it keeps happening, look in the dev server's terminal for a [guijam] line, such as "daemon unavailable", and in .guijam/logs/gjd.log. Run npx guijam doctor to check the gjd binary.
The dev server did not answer#
The dev server did not answer.
Check the dev server's terminal for errors, then retry.
A drawing stopped during a reload#
This drawing stopped while the page was reloading.
Generate it again.
Library installs#
<command>failed
no
<package>release is at least 14 days old
GUIJam installs only releases that are at least 14 days old. Install the library yourself, then pick the variant again.
Attachments#
<name>isn't an image GUIJam can use. Attach a PNG, JPEG, WebP or GIF.
<name>is<size>MB; images can be up to 20 MB.
Convert or resize the image, then attach it again.