“Connection failed” or “couldn’t authenticate” with Shopify
You typed your store handle on the Shopify connect page, the OAuth window opened (or didn’t), and something went wrong. Symptoms look like: Specter says it couldn’t reach the store, the OAuth window closes without completing, Shopify shows an error before you even see Specter’s permission screen, or the Mac app never receives the handoff. Almost always one of the six causes below.
1. Wrong store handle on the setup page
The single most common one. Specter wants your store handle — the part before .myshopify.com. If your admin URL is https://acme-supply.myshopify.com/admin, the handle is acme-supply.
The form on /shopify/setup accepts both the bare handle and the full your-store.myshopify.com address, but if you pasted in your custom domain (shop.acmesupply.com) or a partial URL with extra path on it, the OAuth call won’t find a store. Fix: go back to the setup page and type just acme-supply.
2. Pop-up blocker stopped the OAuth window
OAuth opens a new window to Shopify so you can approve the install. If your browser blocked the pop-up, you may have seen nothing happen, or a tiny “blocked” indicator in the address bar.
Fix: allow pop-ups for spectersync.com (or for the page you started from), and try again. If you’re in a strict-privacy browser like Brave or Safari with content blockers cranked up, temporarily relax them for the connect flow.
3. Your Mac didn’t catch the deep-link back to Specter
Shopify’s approval flow ends by handing off back to the Specter Mac app via a deep link (specter://...). If Specter wasn’t running, or macOS didn’t route the link, you can land on a “you’re connected — return to Specter” page but the app never picks it up.
Fix: make sure Specter is running (you’ll see the menu-bar icon), then click “Connect Shopify store” again from the setup page. If macOS asks whether you want to allow the deep link, say yes.
4. Your staff account can’t install apps
If you’re logged into Shopify as a staff member rather than the store owner, Shopify won’t let you complete an app install unless your role has the “Manage and install apps” permission. The OAuth window will show a permissions error rather than the Specter approval screen.
Fix: either ask the store owner to grant your staff account the install permission, or have the owner complete the connection from their own account. More on what each role can do in Shopify app permissions explained.
5. The store’s plan restricts app installs
Some Shopify plans, and most notably development stores under certain configurations, block app installs by default until the plan is upgraded or the dev-store restrictions are lifted. Shopify shows a plan-related message rather than letting you approve.
Fix: check the store’s plan in Shopify admin under Settings → Plan. If it’s a dev store, transfer it to a paid plan or have the dev-store partner enable installs. If it’s a paid plan with restrictions, contact Shopify support to confirm what’s blocking.
6. Specter was previously installed and partially uninstalled
If you (or someone with admin access) installed Specter before, then removed it without fully uninstalling on Shopify’s side, the next install can hit a stale-state error. Same thing happens if the install was interrupted mid-flow.
Fix: go to Shopify admin → Settings → Apps and sales channels, look for any existing Specter entry, and remove it cleanly. Then return to /shopify/setup and start the connection fresh.
Still stuck
If you’ve ruled out all six, the next step is Shopify says ‘app cannot be installed’, which covers errors that show up on Shopify’s approval screen specifically. Or jump back to the connect-your-store guide for the happy-path walkthrough. If none of that helps, email support@spectersync.com with a screenshot of the error — that’s almost always faster than guessing.