Troubleshooting

Common issues and how to fix them.

BigQuery connection issues

"Could not connect to BigQuery" or credentials error

Your service account JSON may be invalid or incomplete.

  • Re-download the JSON key from Google Cloud Console
  • Make sure you're uploading the JSON key file, not the service account email or ID
  • The JSON file should contain type, project_id, private_key, and client_email fields

"Access Denied" or "Permission denied" on queries

The service account doesn't have the right BigQuery permissions.

  1. Go to IAM & Admin in your GCP project
  2. Find your service account email
  3. Make sure it has at least the BigQuery Data Viewer and BigQuery Job User roles
  4. If querying across projects, grant access in both the data project and the billing project

"Project not found"

  • Verify the project_id in your service account JSON matches an active GCP project
  • Make sure the BigQuery API is enabled: go to APIs & Services > Library and search for "BigQuery API"

Deploy failures

"Not authenticated" when deploying

The CLI has no saved credentials on this machine.

  • Run npx @overscore/cli auth to check your status
  • If you're not logged in, run npx @overscore/cli auth login. It opens a browser, you approve, and the credentials are saved to ~/.overscore/config. You do this once per machine.
  • There is no API key to set. The CLI does not read an OVERSCORE_API_KEY environment variable.

"Build failed" during deploy

Your dashboard has a build error that needs to be fixed locally first.

  1. Run npm run build locally and fix any errors
  2. Common causes: missing imports, TypeScript errors, or referencing browser APIs at build time
  3. Make sure all dependencies are in package.json (not just installed globally)

"Dashboard not found" or "Invalid slug"

  • VITE_OVERSCORE_DASHBOARD_SLUG in the dashboard folder's .env must match one you've created in the Hub
  • Slugs are case-sensitive and can only contain lowercase letters, numbers, and hyphens
  • Double-check your project slug too — the deploy target is project-slug/dashboard-slug

Query errors

BigQuery date objects returning as strings

BigQuery DATE and TIMESTAMP types get serialized as strings in JSON responses. Parse them in your frontend:

// BigQuery returns dates as "2024-01-15" strings
const date = new Date(row.created_date);

CORS errors when querying

You should never call BigQuery directly from the browser. All queries go through the Overscore proxy API.

  • Use the useQuery hook from @overscore/client — it handles routing automatically
  • If you see CORS errors, make sure you're using the hook and not making direct fetch calls to BigQuery
  • Check that VITE_OVERSCORE_PROJECT_SLUG in the dashboard folder's .env is correct

Query timeout

BigQuery queries that scan large amounts of data may time out.

  • Add LIMIT clauses to your queries during development
  • Use date filters to reduce the scan range
  • Consider creating materialized views or summary tables in BigQuery
  • The default timeout is 30 seconds — if you consistently need more, optimize your queries

Authentication issues

Google OAuth redirect not working

After clicking "Sign in with Google," you get an error or blank page.

  • Make sure you're accessing Overscore from the correct URL (not localhost in production)
  • Clear your browser cookies for the site and try again
  • If you see "redirect_uri_mismatch," this is a server configuration issue — contact support

CLI commands fail with an authentication error

  • Run npx @overscore/cli auth to see whether this machine is logged in. If it isn't, run npx @overscore/cli auth login and approve in the browser.
  • Your saved credentials may have expired or been revoked. Log in again with npx @overscore/cli auth login. You can see and revoke devices in the Hub under Settings > Devices.

The CLI can't find your dashboard

  • You may be pointed at the wrong project. Run npx @overscore/cli projects to list the projects on your account, then check VITE_OVERSCORE_PROJECT_SLUG and VITE_OVERSCORE_DASHBOARD_SLUG in the dashboard folder's .env.

"Not authorized" when viewing a dashboard

  • The viewer needs to be added to the project's team members in the Hub
  • Ask the project owner to add their Google email on the project's Members page
  • Viewers must sign in with the same Google account that was invited

Caching issues

Stale data showing after BigQuery update

If you've updated data in BigQuery but the dashboard still shows old values:

  • Caching respects the TTL (time-to-live) you set on each query
  • Wait for the TTL to expire, or set a shorter TTL during development
  • You can force a refresh by clearing the cache in the Hub under your dashboard's settings

DuckDB-WASM errors in the browser

The local caching layer uses DuckDB-WASM and occasionally hits browser-specific issues.

  • Make sure you're using a modern browser (Chrome 90+, Firefox 90+, Safari 15+)
  • Try clearing your browser's IndexedDB storage for the site
  • If the error persists, turn caching off for the dashboard in the Hub under its Settings tab. useQuery takes a query name, and optionally SQL and a dependency array — there is no per-call caching option.

"Cache miss" on every request

  • Verify that caching is enabled in your dashboard settings in the Hub
  • Check that the TTL is set to a value greater than 0
  • The cache is per-browser — each user builds their own local cache on first visit

Still stuck?