Troubleshooting

Troubleshooting

First step for almost anything: pm2 logs opengsc --lines 200 on the server. OpenGSC logs the real reason (provider status, Google error, failing step) instead of a generic error.

Sign-in

redirect_uri_mismatch

NEXTAUTH_URL in .env doesn't match the Authorized redirect URI in Google Cloud. They must be identical, including http vs https, plus /api/auth/callback/google:

NEXTAUTH_URL="https://gsc.example.com"
redirect URI:  https://gsc.example.com/api/auth/callback/google

After editing .env: pm2 restart opengsc --update-env. If you installed without SSL, NEXTAUTH_URL is http://…; either use http:// in Google too or add SSL and switch both to https://.

access_denied from Google

The OAuth app is in Testing and your account isn't under Test users. Add it, or publish the app. See Google Cloud Setup.

Endless redirect back to /login

NEXTAUTH_URL doesn't match the address you're opening (domain, scheme, port), or the SSL certificate is invalid. Open the app at exactly the NEXTAUTH_URL address.

"Use your password" / Google sign-in refused

Working as designed:

• After the owner sets a password, Google is no longer a login, only a way to connect data accounts. Sign in with e-mail + password. To reopen Google login: OPENGSC_ALLOW_GOOGLE_LOGIN=true in .env, restart.
• A Google account that isn't the owner's is refused at the login page. Team members sign in with the e-mail/password they were given.
• On a fresh instance with OPENGSC_OWNER_EMAIL set, only those addresses can claim ownership.

Forgot the password

cd /root/opengsc && npm run set-password -- --email you@example.com

Someone else became the owner

The first Google sign-in on a fresh instance wins. Reset ownership from the console: npm run create-owner -- --email you@example.com --force. Next time set OPENGSC_OWNER_EMAIL before exposing a fresh instance.

Data

Dashboard shows no sites

1. Settings → My Google Accounts: is the account connected with GSC ✓? If not, Reconnect.
2. Does that Google account have the properties in Search Console?
3. Press Sync Data and watch pm2 logs opengsc for [GSC Sync] lines.

Google accounts disconnect about once a week

Your OAuth app's publishing status is Testing, where Google refresh tokens expire after 7 days. Publish the app (Audience → Publish app) and reconnect the accounts once. See Google Cloud Setup.

Data is two days behind

Normal. Search Console publishes a day's data about two days later. Comparisons use complete days only.

Data doesn't update by itself

Automatic sync is off by default. Turn it on in Settings → Sync.

"Table not available", notMigrated, "run prisma db push"

The code was updated but the database schema wasn't. Run:

cd /root/opengsc && npx prisma db push && pm2 restart opengsc

update.sh and the UI updater do this automatically. A bare git pull doesn't.

The database "disappeared" after a restart

DATABASE_URL is relative and resolved against a different working directory. Use an absolute path: file:/root/opengsc/data/prod.db. The old file is usually still there; find it with find / -name "*.db" -path "*opengsc*" 2>/dev/null.

Install, build and update

Build ends with a bare Killed

Out of memory. The build needs about 2.4 GB. Add swap and retry (Installation → Memory and swap). install.sh and update.sh add swap themselves; manual builds don't.

Build fails on the first stylesheet / Tailwind / TypeScript missing

Dependencies were installed without dev packages (PM2 sets NODE_ENV=production). Use npm i --include=dev, then npm run build.

Changes don't appear after git pull

The running app is the old build. Rebuild: npm i --include=dev && npx prisma db push && npm run build && pm2 restart opengsc. Better: bash update.sh.

Update hangs at "backing up SQLite"

The database has grown, usually because of raw indexer logs. Run node scripts/rollup-logs.ts (deletes raw IndexerLog rows except the latest 5,000; charts are kept), then update again. See Updating.

The update failed. Is the app broken?

update.sh rolls back on failure: previous commit, previous dependencies, previous build, app started again. The log names the failing step. If it says "no previous build to restore — the app stays STOPPED", fix the cause (often memory or disk) and run bash update.sh again.

Nginx shows 502 Bad Gateway

The app isn't running. pm2 status; if opengsc is stopped or errored, pm2 logs opengsc shows why, then pm2 restart opengsc. Mid-update this is expected for a few minutes.

Other PM2 apps on the server stopped during an update

Set PM2_PROC_NAME=opengsc in .env so the updater stops only OpenGSC.

Integrations

GA4 tab empty or erroring

Error	Fix
… API has not been used in project … or it is disabled	Enable Analytics Data API and Admin API in the OAuth client's project
insufficient authentication scopes	Reconnect the account until it shows GA4 ✓
Empty property list	Give the account Viewer access to the property in Google Analytics

Health checks: Safe Browsing / PageSpeed errors

Usually key restrictions. Server-side calls have no referer, so don't use "Websites" restrictions, and include IPv6 if you restrict by IP. See Health check keys.

AI generation fails (generation_failed)

Open the job in SEO Tools → History: the error carries the provider's reason (invalid key, quota exhausted, context too long, content-policy rejection). Also [LLM] lines in pm2 logs opengsc.

Backlink or metrics provider returns 503 / 429

429 is rate limiting; OpenGSC queues and retries. A persistent 503 from a reseller gateway is the gateway's problem. Check its status, or switch to DataForSEO or Majestic, which are cheap and reliable for link data. Failed requests are logged in Settings → Provider log.

Bing / Yandex buttons don't appear

The key or token isn't saved, or the page needs a reload. For Bing use the API Key method, not OAuth. See Indexing.

A-Parser features say "not configured" or fail

Check the base URL and API password (Settings → SERP & scraping, or OPENGSC_APARSER_* in .env, which wins). If you changed the password in A-Parser, update it here too. In Docker, 127.0.0.1 is the container; use the host's IP.

Uptime says a working site is down (403)

A WAF blocks the checker's User-Agent. Add 403 to the site's accepted codes: 200-399,403.

Notifications don't arrive

Press Send test on the channel. Check its event filter. SMTP: Gmail needs an app password; many VPS providers block outbound SMTP. Telegram: message your bot first, then Detect chat id.

MCP client can't connect

See MCP Server → Troubleshooting. For Claude Desktop, put ?token=… on the URL and leave Advanced settings empty.

Browser extension: 403 origin_not_allowed

Copy the extension ID into Settings → Integrations → Browser extension → Allowed extension IDs.

Auditing a local/staging site is refused

Private addresses are blocked by default (SSRF protection). Set OPENGSC_ALLOW_PRIVATE_TARGETS=1 in .env.

Still stuck?

Open an issue with your version (bottom of the user menu), what you did, what you expected, and a pm2 logs opengsc excerpt. Remove keys and e-mails from the logs first.