Troubleshooting

This page lists common problems and how to fix them. If yours is not here, ask for help and attach a support file. See Report a problem.

Figure: When an agent can’t start, its terminal says why.

An agent does not start

Look at the terminal first. When an agent can’t start, the terminal says why, in a line such as Codex can’t start: codex is not installed (it is not on PATH).

The agent is not installed

Cuewire runs each agent’s own command-line tool. It looks for the tool on your PATH:

On the Start here card, an agent Cuewire can’t find shows (not installed).

1. Install the agent’s tool, as its maker describes.
2. Open a new terminal outside Cuewire and run the tool, for example codex --version. If this fails, the tool is not on your PATH yet.
3. Quit Cuewire with Ctrl+Q and open it again. Cuewire looks for agents when it starts.
4. Right-click the terminal and choose Restart.

The terminal says “… is only installed as a script …”

On Windows, Cuewire found only a script for the agent, such as a .bat, .ps1 or .cmd file. Cuewire does not run these scripts. Windows runs them through cmd.exe, which could read parts of a prompt as commands.

Most tools installed with npm are different. Their .cmd script only starts Node.js on the tool’s JavaScript file. Cuewire starts Node.js on that file itself, without the script. For example, npm install -g @google/gemini-cli works for Gemini CLI.

To fix it, install the agent’s native build (its .exe). Then quit Cuewire, open it again, and restart the terminal.

The terminal says “… installed with npm …, but Node.js was not found”

The agent was installed with npm, so Cuewire starts it with Node.js. Cuewire looked for node.exe next to the agent’s script and on your PATH, and found neither.

1. Install Node.js from nodejs.org.
2. Open a new terminal outside Cuewire and run node --version. If this fails, Node.js is not on your PATH yet.
3. Quit Cuewire with Ctrl+Q and open it again.
4. Right-click the terminal and choose Restart.

The terminal says “Waiting: … (the cap; change it under Usage)”

You set a limit on how many agents of one kind may run at once. The new agent waits until one of the others stops. To raise the limit:

1. Click the usage chip at the bottom left.
2. Under At once (concurrency caps), click + next to the agent.

The waiting agent starts as soon as there is room.

The terminal says “Waiting: the Free plan runs 3 agents at once …”

The Free plan runs up to 3 agents at the same time. The new agent waits, and starts by itself as soon as one of the others stops. Stop an agent you don’t need, or upgrade to Pro for no limit. See Plans, the free trial and pricing.

“… can’t be opened: the Free plan works with 1 remote computer”

Your projects already use another remote computer, and the Free plan works with one. Upgrade to Pro, or remove that computer’s projects from the sidebar.

The terminal says “Process exited” or “Process failed”

The program in the terminal ended. Scroll up to read its last output. Then right-click the terminal and choose Restart.

The terminal says “can’t start” for another reason

Read the rest of the line. It names what stopped the agent, for example:

• … can’t start in its sandbox: Docker is needed …: the project runs agents in a sandbox, and Docker is not installed. See Sandboxes and safety.
• … your organisation does not allow …: your organisation’s policy forbids this agent or this option. Ask your administrator. See For administrators.

The terminal says “Draft in this layer”

The terminal came with a new layer and has not started yet. Right-click it and choose Start in this layer. See Projects and layers.

Terminals stay on “Starting the terminal service…”

Cuewire can’t reach its background service, which runs every terminal.

1. Wait a few seconds. The service may still be starting.
2. If an error shows instead, read it.
3. Quit Cuewire with Ctrl+Q and open it again.
4. If it still fails, report a problem. The support file holds the end of the service’s log.

A prompt is not sent

• Select one or more agents to prompt: the selection has no agent. A terminal that runs a plain shell takes no prompts. Select an agent’s terminal and try again.
• None of them is running; start them first: the agents have not started yet, or have stopped. Wait for them, or right-click and choose Restart.

Codex shows “Hooks need review”

Codex asks you to trust the hooks that Cuewire gives it. Press 2 to choose Trust all and continue, then press Enter. See Trust Cuewire’s hooks in Codex.

Codex’s reason is always “Would you like to run the following command?”

Codex’s hooks don’t run, so Cuewire reads its screen. Check these:

• Codex is 0.162 or newer. Open a terminal outside Cuewire and run codex --version.
• You trusted the hooks. If not, quit Cuewire, open it again and start Codex. Codex asks once more.
• Codex runs on this computer. Agents on a remote computer or in a sandbox always use the screen.

After you update Codex, quit Cuewire and open it again. Cuewire checks the version when it starts.

Two nodes don’t connect

Cuewire says these nodes cannot be connected; a terminal connects to a terminal, a note, or a portal. Wires always have a terminal at one end. Two notes, for example, can’t be wired.

The sign-in code does not arrive

When you sign in, Cuewire emails you a code.

1. Look in your spam or junk folder. Mark the email as not spam, so the next one arrives.
2. Check the address in Enter the code sent to …. If it is wrong, click Use another email and type it again.
3. Wait a minute, then ask for a new code with Email me a code.

A code works for 15 minutes. See Sign in.

The phone shows only the heading

The companion page did not load fully on your phone.

1. On the phone, close that browser tab.
2. On the desktop, open the command palette and choose Pair a phone or browser….
3. Choose Pair a device and scan the new code with the phone.

See Your phone as a companion.

Windows says “Windows protected your PC”

This build of Cuewire is not signed. Click More info, then Run anyway, if the file came from the Cuewire team. See Install Cuewire.

“Workspace was not saved”

A red message at the top left says Workspace was not saved: and the reason. Cuewire could not write your canvas to disk.

• Check that your disk has free space.
• Check that you can write to %LOCALAPPDATA%\Cuewire.

Cuewire tries again with your next change. The message goes away once a save works.

“This canvas was saved by a newer Cuewire”

The canvas was saved by a newer version of Cuewire, maybe on another computer. You can look at it, but Cuewire does not save changes to it. Install the newer version. See Update Cuewire.

No notifications or sounds

• Windows notifications come only when Cuewire is in the background, or the agent is off screen. Check that Windows allows notifications from Cuewire.
• For sounds, open the command palette. If it offers Turn sound cues on, the sounds are off. Choose it to turn them on. Sound volume: … sets how loud they are.

Where the logs are

Cuewire writes a log every day:

The logs hold no terminal output, prompts or note text.

Which version do I have?

Click Cuewire at the top of the sidebar. Or open the command palette (Ctrl+K) and choose About Cuewire. The About Cuewire window shows:

• Version: the release, for example 0.1.0;
• Commit and its date: the exact code this build was made from;
• Built: when this build was made;
• Background service: the version and commit of the service that keeps your agents running;
• System: your operating system.

Click Copy to put all of it on the clipboard, for example to paste into a message.

Figure: About Cuewire. Your version and commit will be different.

Note

After an update, the background service keeps running its old build until it restarts, so your agents keep running. Then About says The background service runs another build. Click Update ready in the sidebar when you are ready, or quit Cuewire while no agent runs.

Report a problem

When you ask for help, attach a support file. You read all of it before it leaves your computer.

1. Open the command palette (Ctrl+K) and choose Report a problem….
2. Read the support file. It holds the Cuewire version and commit, your platform, the last crash, and the end of the app’s and the service’s logs. Cuewire takes out your home folder, your name, email addresses and anything that looks like a key.
3. Click Save to a file. The file goes to your Downloads folder, named cuewire-support-<number>.txt. Or click Copy.
4. Click Show in folder to find the file.
5. Attach the file where you ask for help.

Cuewire sends nothing by itself from this sheet.

Figure: Report a problem… shows the whole support file before you save it.

What’s next

• Keyboard shortcuts
• Glossary
• Install Cuewire