Troubleshooting & FAQ
Common Problems
| Symptom | Fix |
|---|---|
| "Private key file not found", or "No private key found" | Put AuthKey_<KEY_ID>.p8 in ./keys, or paste the key in Settings > App Store Connect. The file name must match the Key ID. |
| "Missing App Store Connect Key ID or Issuer ID" | Set ASC_KEY_ID and ASC_ISSUER_ID in .env, or enter them in Settings. |
Sales sections are empty and the sync dialog shows HTTP 403 | The key lacks the Sales role. Create a key with Sales, Finance or Admin and enter it. |
| "Vendor number is not set" | Add ASC_VENDOR_NUMBER, or enter it in Settings. It's in App Store Connect under Payments and Financial Reports. |
| Impressions say they need a one-time setup | Enter an Admin key once and sync, then switch back to your Sales key. See Impressions and Product Page Views. |
| Impressions show "Apple is preparing (1–2 days)" | Normal after the setup. Apple takes a day or two to generate the first reports. |
| The newest day or two show as "to fetch" | Normal. Apple publishes daily reports with a delay, and they're retried on every sync. |
| "Too many attempts" on sign-in | Wait it out, at most 15 minutes. Restarting the container also clears it. |
| "This hostname is not allowed" | You're running without a password under a hostname that isn't local. Add it to OPENCONNECT_ALLOWED_HOSTS. |
| Marketing cards won't download | Your browser blocks downloads on http:// pages that aren't localhost. Use the Tailscale HTTPS address, or click PNG and save the image from the new tab. |
| "The screenshot studio renderer is not reachable" | The openconnect-studio container isn't running. Check docker compose ps and docker logs openconnect-studio. |
appshot says "Invalid or revoked API token" | Create a new token in Settings > Security > API tokens and update OPENCONNECT_TOKEN. |
Where Do I Find the Setup Code?
In the server log:
docker logs openconnectWithout Docker, it's printed in the terminal running npm run dev. A new code is made each time the server starts until a password is set.
Can't Reach the Dashboard From Another Device
OpenConnect only accepts connections from its own computer by default. Set BIND_ADDRESS=0.0.0.0 in .env and run docker compose up -d, or use Tailscale.
Is Data Synced in Real Time?
No. Apple publishes sales reports once a day, with a delay, so OpenConnect checks every 6 hours by default. Ratings and rankings are checked once a day. You can run either job at any time from the Sync dialog.
Why Are My Proceeds a Little Different From App Store Connect?
OpenConnect converts every report's currency to US dollars with the latest exchange rates, for all dates, and then to your display currency, so totals in other currencies are estimates. See Currencies.
Can I Track Only Some Storefronts?
Ratings and rankings are checked in all 175 storefronts. To make the check faster, switch off charts you don't need in Settings > Sync > Charts to check for rankings.
Can I Run It on a Server or NAS?
Yes. Any machine that runs Docker on Intel or ARM works. Keep it off the public internet and reach it over your home network or Tailscale.