Troubleshooting

The fixes for the most common problems. Every message about a problem ends with a code, such as (ZK-CAD-003); the code's page at zirkle.app/errors/ followed by the code has its full text and what to do. If nothing here helps, contact support.

Your AI app says Zirkle isn't connected

Your AI apps read their tools only when they start Zirkle, so a restart fixes most connection problems.

1. Claude: closing the window is not enough. Right-click the Claude icon in the corner of the taskbar, next to the clock (click ^ if you don't see it), and choose Quit. Then open Claude again. See ZK-SET-021.
2. ChatGPT: open Settings → MCP servers, check that zirkle is listed, and select Restart. If it isn't listed, quit ChatGPT completely and open it again. Then switch to Work with the toggle above the message box and start a new conversation. Local tools like Zirkle need a ChatGPT Plus plan or higher. See ZK-SET-020.
3. Open Zirkle Settings from the Start menu. In Status, each AI app shows its state: "Using Zirkle" or "Connected, waiting for first use" is fine; "Not connected" needs Connect; "Zirkle can't read Claude's settings file" needs Help → Repair AI app settings.

Zirkle's tools are missing or old after an update

AI apps keep the tool list they read at start. After Zirkle updates, or after you turn a toolset, the Advanced tool or Power mode on, quit the AI app completely and open it again (as above). The connection check ("Is Zirkle connected?") says "Restart … to get the new tools" when a restart is pending.

A tool the AI says is turned off is in a toolset that is off: turn it on in Zirkle Settings → Toolsets, then restart the AI app. See ZK-TOOL-001.

Your CAD isn't found or isn't running

• Your CAD isn't open: open your drawing, or ask the AI to start your CAD. The CAD Zirkle starts is the one chosen in Setup or in Zirkle Settings → Status → CAD programs. See ZK-CAD-001.
• Your CAD is open but no drawing is: open one, or ask for a new drawing. See ZK-CAD-002.
• The open CAD isn't supported: AutoCAD LT, a version before 2022 or an edition that doesn't let other programs control it. See ZK-CAD-012 and Compatibility.

Zirkle controls the wrong CAD

When several copies of your CAD are open, Zirkle uses the one whose window is in front, or the one used last. If it can't tell, it stops and asks: click into the CAD window you are working in, then ask again. The connection check says which CAD and which drawing Zirkle is using. See ZK-CAD-007.

Your CAD was started as administrator

Zirkle can't reach a CAD running with elevated rights. Close your CAD and open it again from the Start menu, without "Run as administrator". See ZK-CAD-004.

Your CAD is busy

A command or a dialog is open in your CAD, so Zirkle doesn't change anything. Finish or cancel it there (press Esc), then ask again. See ZK-CAD-003. If your CAD is still waiting for a click Zirkle asked for, press Esc there (ZK-PICK-002).

Zirkle can't change the drawing

• Read-only is on. Turn it off in Zirkle Settings → Safety. Read-only turned on by asking the AI ("Don't change anything") also ends when the AI app restarts Zirkle. See ZK-RO-001.
• The trial has ended. Reading and explaining drawings keep working; drawing and editing need a licence from zirkle.app/buy, pasted in Zirkle Settings → License. See ZK-LIC-001.
• The licence file can't be read. Open Zirkle Settings → License and choose Repair license file; if this PC had a licence, paste your key again. See ZK-LIC-011.
• The drawing was opened read-only in your CAD, so Zirkle can't save over it: save it under a new name. See ZK-FILE-004.
• The objects are on a locked layer. Unlock the layer in your CAD, or leave those objects out. See ZK-EDIT-006.

The licence key is refused

• "Zirkle doesn't know this license key": check the key against your email, or get it sent again at zirkle.app/license/resend. See ZK-LIC-020.
• "This license key is already active on another PC": free the other PC at zirkle.app/license/move, then paste the key again. The key can move twice a year (ZK-LIC-022). See ZK-LIC-021.
• "That isn't a Zirkle license key or code": paste the whole key from your email; it starts with ZK-. See ZK-LIC-019.
• "Zirkle couldn't reach zirkle.app": the key needs one online check. Connect the PC to the internet once and try again; a PC that never goes online follows the steps under No internet on this PC? in Zirkle Settings → License. See ZK-LIC-023.
• "Too many attempts right now": wait a minute and try again.

Undo is refused

• "I have no changes of mine on record": Zirkle's record starts fresh whenever your AI app restarts it. Press Ctrl+Z in your CAD. See ZK-UNDO-001.
• "The drawing has changed since my last edit": you edited the drawing yourself after Zirkle's change, so undoing could remove your own work. Press Ctrl+Z in your CAD to undo step by step. See ZK-UNDO-002.

The screenshot is blank or missing

Zirkle captures your CAD's window as it is on screen. Restore a minimized CAD window and make sure it is visible, then ask again. See ZK-SHOT-002 and ZK-SHOT-003.

Zirkle's settings file is damaged

Zirkle refuses every change until its own settings file reads again, rather than falling back to defaults silently. Open Zirkle Settings; it offers Reset settings to defaults. Your licence and backups are kept, and the damaged file is kept in Zirkle's backups folder. See ZK-SET-030.

Setup or an update says Zirkle is in use

Claude or ChatGPT is running Zirkle. Quit it completely (Claude: the icon next to the clock → Quit; ChatGPT: Settings → MCP servers, or quit the app), then click Retry. See ZK-SET-002.

Still stuck

Send the diagnostic report: Zirkle Settings → Help → Copy diagnostic report, then paste it into an email to support@zirkle.app. It never contains drawing names, file paths or anything read from a drawing. See Support.