BigQuery Troubleshooting

Most BigQuery connection failures fall into three groups: an invalid service account key (authentication), missing BigQuery roles (permissions), or a wrong Project ID or Dataset ID (configuration). The tables below map the errors BigQuery returns to their likely cause and fix.

Common Errors

Error	Likely Cause	Fix
`Access Denied: 403`	The service account lacks the required BigQuery roles	Assign `bigquery.dataViewer` and `bigquery.jobUser` roles to the service account
`Not found: Dataset`	The Dataset ID in the connection form does not exist or the service account cannot see it	Verify the Dataset ID in the BigQuery Console and ensure the service account has `bigquery.dataViewer` on the dataset
`Not found: Project`	The Project ID is incorrect or the service account does not belong to the project	Verify the Project ID in the Google Cloud Console
`The caller does not have bigquery.jobs.create permission`	The service account lacks the `bigquery.jobUser` role	Assign `roles/bigquery.jobUser` to the service account at the project level
`Unable to parse service account key`	The JSON key file is malformed or truncated	Re-download the service account key from IAM & Admin > Service Accounts in the Google Cloud Console

Detailed Notes

Authentication errors

The error Unable to parse service account key means Qualytics could not read the uploaded JSON key file, usually because it was modified or truncated after download. Re-download the key and upload it again.

A key that parses but no longer works fails on Google's side instead. Common causes:

Key deleted or disabled: the key was deleted or disabled on the service account in the Google Cloud Console.
Wrong project: the service account belongs to a different Google Cloud project than the one specified in the Project ID field, which surfaces as Not found: Project or a permission error.

Note

Service account keys do not expire, but they can be deleted or disabled by project administrators. If the key stops working, verify its status in IAM & Admin > Service Accounts > Keys.

Permission errors

The error Access Denied: 403 or The caller does not have bigquery.jobs.create permission means the service account authenticated successfully but lacks the required roles.

Common causes:

Missing bigquery.jobUser: the service account cannot run queries without this role. It must be assigned at the project level.
Missing bigquery.dataViewer: the service account cannot read dataset or table metadata.
Missing bigquery.readSessionUser: the service account cannot create read sessions for efficient data retrieval via the Storage Read API.
Dataset-level vs. project-level: some roles are assigned at the dataset level but the operation requires project-level access (e.g., bigquery.jobUser).

Configuration errors

The error Not found: Dataset or Not found: Project indicates a configuration issue with the Project ID or Dataset ID.

Common causes:

Wrong Project ID: the Project ID does not match the Google Cloud project.
Wrong Dataset ID: the Dataset ID was misspelled or does not exist in the specified project.
Regional mismatch: the temp dataset is in a different region than the source dataset, causing cross-region query failures. See Create a BigQuery Temp Dataset.

Tip

Investigate in the order BigQuery evaluates requests: first confirm the service account key is valid (authentication errors), then verify the BigQuery roles (permission errors), and finally check the Project ID and Dataset ID (configuration errors).