Fixing a Failed Install

5 min read Updated Oct 2026

Anyone whose HQ install stopped partway through, or who can't get the app open or signed in. Find your symptom below and follow the fix.

HQ installs from one app: you download it, open it, sign in, pick a folder, click Install here, then finish guided setup in the HQ window. This page is organized by what you're seeing. Scan the headings, find yours, and follow the steps.

For the normal walkthrough, see Installing HQ on macOS or Installing HQ on Windows. If your install finished but HQ isn't behaving, go to The "I'm Stuck" Guide instead.

The download won't open#

macOS: drag HQ from the disk image onto Applications and open it from Applications, not from the disk image. If macOS warns that it can't check the app for malicious software, report it with /hq-bug or to your usual support contact. HQ is notarized by Apple, so that warning is a bug.
Windows: HQ is digitally signed. If SmartScreen still shows "Windows protected your PC," click More info, then Run anyway.
Linux: there's no Linux version yet. The install page has a waitlist.

HQ signs in with Google or Microsoft. There's no separate HQ password.

The browser didn't open. Click the sign-in button again. If a browser still doesn't open, check that you have a default browser set.
You signed in, but HQ didn't notice. When sign-in works, the browser tab says You are signed in and usually closes itself. Go back to the HQ window and wait a few seconds. If the first attempt expired or got mixed up, HQ quietly tries once more on its own. If it's still stuck, close the browser tab and click the sign-in button again.
"Sign-in could not open a registered local callback port." Another app or sign-in window is using the port HQ needs. Close other sign-in windows, then try again.
"Sign-in took too long" or "That sign-in attempt no longer matches." Click Continue with Google or Continue with Microsoft to start again.
Your team can't see you. Sign in with the same email address your team invite went to.

"Does not look like an HQ folder"#

On the It's a folder screen, HQ won't install into a folder that already has other files in it. Pick an empty folder, keep the suggested hq folder, or pick a folder that's already an HQ folder.

The install didn't finish#

HQ retries failed steps on its own. You'll see Retrying, attempt 2 of 3… or similar. Give it a minute.
If you see a Retry button, click it. If it still fails at the same point, quit HQ, reopen it, and try again.
If it still fails, finish the install from an AI tool: open your HQ folder in Claude Code or Codex and run /setup. It checks the install and repairs what it can.

If the download stalls, check your connection. On a corporate network that inspects secure traffic, try a personal network or a phone hotspot, then retry. Make sure you have a few hundred MB of free disk space.

Stuck on "Your coding tools"#

Your assistant runs through your own coding tool, so guided setup won't continue until Claude Code or Codex is signed in. One is enough, and this step can't be skipped.

Click Sign in next to Claude Code or Codex. Your browser opens.
Finish signing in there. Your password never goes to HQ.
Go back to HQ. It notices on its own and shows Ready.

If it doesn't show Ready:

The browser didn't open. Click Sign in again, and check that you have a default browser set.
You signed in but HQ didn't notice. Wait a few seconds, then click Sign in again.
It still won't finish. Open your HQ folder in Claude Code or Codex yourself and run /setup.

More detail for each tool: Using HQ with Claude Code and Using HQ with Codex.

"Open in Claude Code" or "Open in Codex" did nothing#

Open Claude Code or Codex yourself and point it at your HQ folder (the one you chose during install).
If Claude asks whether you trust the folder, say yes.
Type /setup and press Return. If that works, you're fully installed. Report the button with /hq-bug when you get a chance.

No HQ icon after installing#

HQ runs from your menu bar (Mac) or system tray (Windows). Clicking the icon opens the HQ window. Right-click it for Sync Now, Quit HQ, and more.

On a Mac, look at the top-right of your screen near the clock. On Windows, look at the bottom-right and click the ^ arrow to see hidden icons.
If it's not there, open HQ again from Applications (Mac) or the Start menu (Windows).
HQ starts at login by default. If it doesn't, check Settings → General → Launch at login.

Setting up your company or team#

If you were invited to a team, your company appears once you sign in with the invited email address, and it syncs to your computer by itself. If that sync fails, an Added to banner with your company's name appears in the HQ window. Click Sync now there. To create a new company, pick Start a company on the Your team step of guided setup, or run /onboard in Claude Code or Codex. See first-30-minutes.md and The "I'm Stuck" Guide.

Common questions#

Do I have to start the whole install over after a failure?

Almost never. Retry the step, and if that doesn't work, run /setup in your HQ folder. It checks and repairs most issues.

Did a failed install leave junk on my machine?

No. HQ's work lives in the HQ folder you chose (hq in your home folder by default), plus the supporting tools it installs in its own folder (~/Library/Application Support/Indigo HQ on a Mac, or %LOCALAPPDATA%\IndigoHQ on Windows) and a few settings files in a hidden .hq folder in your home folder. Retrying continues where it left off.

If you get stuck#

If a fix above doesn't work after two tries, report it with /hq-bug followed by a short description. It attaches the details automatically. If you can't get far enough to run a command, send your usual support contact three things: what you were doing when it failed, the exact error text, and your operating system version. See Getting More Help.