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

"Missing environment variables"

The CLI couldn't find required configuration.

  • Make sure you have a .env or .env.local file with your OVERSCORE_API_KEY
  • You can also pass it inline: OVERSCORE_API_KEY=your-key npx @overscore/cli deploy
  • Check that your API key hasn't been revoked in the Hub under project settings

"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"

  • The dashboard slug in your overscore.config.ts 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 your overscore.config.ts has the correct projectSlug

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

"Invalid API key"

  • API keys are scoped to a project. Make sure you're using the key for the right project
  • Check if the key was deleted or regenerated in the Hub
  • API keys are shown once when created — if you lost it, generate a new one

"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 under Settings > Team
  • 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, disable caching by setting cache: false in your query options:
useQuery("my_query", { params: {}, cache: false });

"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?