Skip to main content
Each heading below is the exact wording Onlook shows, so you can search this page for the message you saw. If yours isn’t here, contact us.

​
Signing in to Onlook

Check the email address for typos, then press Continue again.
Press Continue again. If it keeps happening, quit Onlook and reopen it.

​
Connecting your AI

Onlook comes with its own copy of Claude Code, so this usually means that copy is damaged. Download Onlook again, replace the app in Applications, and reopen it. If it keeps happening, contact us.
Claude isn’t signed in on this Mac. Choose Sign in on the card in the chat, and finish in your browser. If Claude shows you a code, paste it into the card. See Connect your AI.
Onlook couldn’t talk to Claude Code. Check your internet connection, then quit and reopen Onlook. Details shows the underlying error, which is useful if you contact us.
Onlook sent Claude a short test message and it didn’t go through. The line under the title says why. If it says Claude is busy or has limited how often this computer can ask, wait a moment. Then choose Check again, or Use ChatGPT instead.
Copy the whole code from the browser again, and paste it into Onlook.
Choose Check again. You may already be signed in.
Onlook shows Finish signing in from the Terminal. Choose Copy, then Open Terminal, paste the line and press Return. When Claude says you’re signed in, choose Check again. See Connect your AI.
Finish signing in from the Terminal: choose Copy, then Open Terminal, paste the line and press Return. Then choose Check again.
Claude refused this sign-in. Check that your Claude account is active and on a plan that includes Claude Code. Then finish signing in from the Terminal and choose Check again.
Onlook installs its own copy of the ChatGPT agent, and setup hasn’t finished. Choose Set up ChatGPT.
Choose Sign in to ChatGPT, and finish in your browser.
Check your internet connection, then quit and reopen Onlook. Details shows the underlying error.
Choose Try again. Setup picks up where it stopped.
Choose Download again. A fresh copy usually fixes it.
Choose Download again to get the current version.

​
Connecting a folder

Onlook only works on a copy of your code. If it can’t make one, it stops rather than working in your folder. Check that the folder still exists and your Mac has free disk space, then try again. If it keeps happening, contact us with the message.
You’ve already connected this folder. Open that project from the projects screen, or pick a different folder.
Onlook copies from your GitHub remote’s main branch. If there’s no remote, it uses a local branch named main. It couldn’t find either. Ask an engineer to check that your clone has its GitHub remote set up and up to date.
Every name Onlook tried is already used by a branch in this repository. Deleting an old Onlook branch frees one up. An engineer can help.

​
Creating a project

While it sets up a project, Onlook narrates each step in the chat. If a step fails, the message names it, and Retry repeats that step. To clear a failed project instead, choose Dismiss. The canvas also says Setup didn’t finish or Your app didn’t start, with To try again, see the message in chat.
Your code holds more than one app, or something else is using the app’s port, so the agent needs you to choose. Answer the question in the chat and choose Send answer.
Check the folder is still where it was, then try again.
Nothing was left behind. Retry makes the copy again.If macOS asked to install command line developer tools, choose Install and wait for it to finish, then choose Retry. See Install Onlook.
Retry runs the install again in the copy. If it fails again, your Mac may be missing a tool the project needs, such as Node.js, or the project may use more than one package manager. Ask an engineer how they install the project. See Before you start.
Installing took too long. Check your internet connection, then choose Retry. Large projects can take a few minutes.
Your project’s package manager reported an error. The detail under the message shows it. Choose Retry. If it fails again, ask an engineer how they install the project.
Retry asks the agent to start the app again. If the project needs settings from a .env file, ask an engineer for it and put it in your original folder, then create the project again.
This appears when starting a project from scratch. It names the step it stopped at. Nothing was left behind. Choose Try again.

​
Frames

A frame shows a message instead of your app when the app isn’t running or couldn’t load.
Your app isn’t running yet. Press Start.
The app Onlook or the agent started has stopped. Press Start.
This frame points at a dev server you started yourself, outside Onlook. Start it again the way you started it before. The frame reconnects on its own.
Something else on your Mac is using that address, so your app can’t start there. Quit the other app or dev server, then press Start.
Your app runs inside Docker or a similar container. Onlook can’t show those yet.
No app is answering at that address. Press Start, or restart your own dev server.
Your app redirected to a secure address your dev server doesn’t serve. Choose Back to your app’s home address. An engineer may need to turn off the https redirect for local development.
The server is fine, but that page didn’t load. Choose Back to your app’s home address, or check the address in the frame.

​
The chat

Choose Retry.
Press send again.
The agent isn’t set up or signed in. See Connect your AI.
You’ve used up your Claude or ChatGPT plan’s limit for now. Nothing was lost. The message says when the limit resets. Then choose Retry.
Claude or ChatGPT didn’t accept your sign-in. Sign in again. See Connect your AI.
Wait for the agent to finish, then send your message again.
Choose Retry. If it keeps happening, contact us with what you asked for.
You can attach PNG, JPEG, GIF or WebP images up to 10MB. The message says which file failed and why.
The frame the agent mentioned was removed. Undo with ⌘Z if you removed it by mistake.

​
GitHub

Your GitHub account can’t reach this repository. Ask someone who owns the repo to give you access.
Your team’s automated checks failed on the pull request. Press Fix Checks, and the agent reads the failures and fixes them.
Your main branch changed the same code you did. Press Resolve Conflicts.

​
The window

You have as many projects open as Onlook allows. To open another, close a tab first.
Choose Reload panel.
A tab stopped responding. Its close button turns into a reload button. Click it to reload the tab.
Onlook couldn’t check for updates, usually because it’s offline. Try Check for Updates… in the Onlook menu later.