> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onlook.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Every message Onlook can show when something goes wrong, what it means, and what to do.

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](/help/contact).

## Signing in to Onlook

<AccordionGroup>
  <Accordion title="That does not look like an email address.">
    Check the email address for typos, then press **Continue** again.
  </Accordion>

  <Accordion title="Onlook could not save your email. Try again.">
    Press **Continue** again. If it keeps happening, quit Onlook and reopen it.
  </Accordion>
</AccordionGroup>

## Connecting your AI

<AccordionGroup>
  <Accordion title="Claude Code is not installed">
    Onlook comes with its own copy of Claude Code, so this usually means that copy is damaged. [Download Onlook](https://onlook.com/install?utm_source=docs\&utm_medium=troubleshooting\&utm_campaign=docs) again, replace the app in Applications, and reopen it. If it keeps happening, [contact us](/help/contact).
  </Accordion>

  <Accordion title="Please sign in to Claude Code to continue designing in Onlook">
    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](/setup/ai).
  </Accordion>

  <Accordion title="Onlook cannot reach Claude">
    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.
  </Accordion>

  <Accordion title="Claude could not be reached">
    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**.
  </Accordion>

  <Accordion title="That code was not accepted. Try pasting it again.">
    Copy the whole code from the browser again, and paste it into Onlook.
  </Accordion>

  <Accordion title="Claude did not answer in time. The sign-in itself may be fine.">
    Choose **Check again**. You may already be signed in.
  </Accordion>

  <Accordion title="The sign-in took too long and was stopped.">
    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](/setup/ai).
  </Accordion>

  <Accordion title="The sign-in stopped before it finished.">
    Finish signing in from the Terminal: choose **Copy**, then **Open Terminal**, paste the line and press Return. Then choose **Check again**.
  </Accordion>

  <Accordion title="The server turned the sign-in away.">
    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**.
  </Accordion>

  <Accordion title="ChatGPT isn’t ready">
    Onlook installs its own copy of the ChatGPT agent, and setup hasn't finished. Choose **Set up ChatGPT**.
  </Accordion>

  <Accordion title="ChatGPT is not signed in">
    Choose **Sign in to ChatGPT**, and finish in your browser.
  </Accordion>

  <Accordion title="Onlook cannot reach ChatGPT">
    Check your internet connection, then quit and reopen Onlook. **Details** shows the underlying error.
  </Accordion>

  <Accordion title="Setting up the ChatGPT agent did not finish">
    Choose **Try again**. Setup picks up where it stopped.
  </Accordion>

  <Accordion title="The ChatGPT agent downloaded but will not start">
    Choose **Download again**. A fresh copy usually fixes it.
  </Accordion>

  <Accordion title="The ChatGPT agent on this computer is older than Onlook needs">
    Choose **Download again** to get the current version.
  </Accordion>
</AccordionGroup>

## Connecting a folder

<AccordionGroup>
  <Accordion title="Onlook could not make a copy of this 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.
  </Accordion>

  <Accordion title="This folder is already in Onlook as …">
    You've already connected this folder. Open that project from the projects screen, or pick a different folder.
  </Accordion>

  <Accordion title="Onlook could not tell which branch is your main one">
    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.
  </Accordion>

  <Accordion title="Onlook could not name a new copy">
    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.
  </Accordion>
</AccordionGroup>

## 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**.

<AccordionGroup>
  <Accordion title="The agent has a question">
    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**.
  </Accordion>

  <Accordion title="Could not read …">
    Check the folder is still where it was, then try again.
  </Accordion>

  <Accordion title="Could not make a copy of …">
    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](/start/install#when-macos-asks-to-install-developer-tools).
  </Accordion>

  <Accordion title="Could not install dependencies for …">
    **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](/start/install#before-you-start).
  </Accordion>

  <Accordion title="… install timed out">
    Installing took too long. Check your internet connection, then choose **Retry**. Large projects can take a few minutes.
  </Accordion>

  <Accordion title="… install failed">
    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.
  </Accordion>

  <Accordion title="Could not start …">
    **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.
  </Accordion>

  <Accordion title="Onlook could not create the project">
    This appears when starting a project from scratch. It names the step it stopped at. Nothing was left behind. Choose **Try again**.
  </Accordion>
</AccordionGroup>

## Frames

A frame shows a message instead of your app when the app isn't running or couldn't load.

<AccordionGroup>
  <Accordion title="Press Start to run this app">
    Your app isn't running yet. Press **Start**.
  </Accordion>

  <Accordion title="The app at … stopped. Press Start to bring it back.">
    The app Onlook or the agent started has stopped. Press **Start**.
  </Accordion>

  <Accordion title="Your server at … is not running. Restart it where you started it to reconnect.">
    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.
  </Accordion>

  <Accordion title="Another process is using … — this app cannot be started there.">
    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**.
  </Accordion>

  <Accordion title="… runs in a container — Onlook can't show containerised apps yet.">
    Your app runs inside Docker or a similar container. Onlook can't show those yet.
  </Accordion>

  <Accordion title="Nothing answered at …. Restart it to reconnect automatically.">
    No app is answering at that address. Press **Start**, or restart your own dev server.
  </Accordion>

  <Accordion title="The page moved to https at …, but your dev server at … serves http, so it could not load.">
    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.
  </Accordion>

  <Accordion title="… did not load (…). Your server at … is running.">
    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.
  </Accordion>
</AccordionGroup>

## The chat

<AccordionGroup>
  <Accordion title="The reply was cut off. Retry sends the same message again.">
    Choose **Retry**.
  </Accordion>

  <Accordion title="That didn’t send. Your message is still here — press send to try again.">
    Press send again.
  </Accordion>

  <Accordion title="… is not available">
    The agent isn't set up or signed in. See [Connect your AI](/setup/ai).
  </Accordion>

  <Accordion title="… limit reached">
    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**.
  </Accordion>

  <Accordion title="The provider rejected these credentials.">
    Claude or ChatGPT didn't accept your sign-in. Sign in again. See [Connect your AI](/setup/ai).
  </Accordion>

  <Accordion title="The agent would not take a message while it was working, so it was not sent.">
    Wait for the agent to finish, then send your message again.
  </Accordion>

  <Accordion title="Something went wrong">
    Choose **Retry**. If it keeps happening, [contact us](/help/contact) with what you asked for.
  </Accordion>

  <Accordion title="Couldn’t attach … ">
    You can attach PNG, JPEG, GIF or WebP images up to 10MB. The message says which file failed and why.
  </Accordion>

  <Accordion title="That frame is no longer on this canvas.">
    The frame the agent mentioned was removed. Undo with ⌘Z if you removed it by mistake.
  </Accordion>
</AccordionGroup>

## GitHub

<AccordionGroup>
  <Accordion title="… · no access for @… · ask an owner">
    Your GitHub account can't reach this repository. Ask someone who owns the repo to give you access.
  </Accordion>

  <Accordion title="Checks Failed">
    Your team's automated checks failed on the pull request. Press **Fix Checks**, and the agent reads the failures and fixes them.
  </Accordion>

  <Accordion title="Conflicts">
    Your main branch changed the same code you did. Press **Resolve Conflicts**.
  </Accordion>
</AccordionGroup>

## The window

<AccordionGroup>
  <Accordion title="Close a project to open another. … is the limit.">
    You have as many projects open as Onlook allows. To open another, close a tab first.
  </Accordion>

  <Accordion title="This panel hit an error and stopped.">
    Choose **Reload panel**.
  </Accordion>

  <Accordion title="Not responding">
    A tab stopped responding. Its close button turns into a reload button. Click it to reload the tab.
  </Accordion>

  <Accordion title="Update check failed">
    Onlook couldn't check for updates, usually because it's offline. Try **Check for Updates…** in the **Onlook** menu later.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.