Skip to main content
Last updated: March 18, 2026
When a sync fails, Detrics classifies the error by pipeline stage to help you identify and fix the issue. This page covers the most common errors and their solutions.

​
Dataset Setup Errors

These errors occur when Detrics can’t access or create the BigQuery dataset.
Error: DATASET_PERMISSION_DENIEDCause: The Detrics service account doesn’t have the required IAM roles in your GCP project.Fix:
  1. Go to Google Cloud Console → IAM
  2. Find the Detrics service account email (shown on your destination page)
  3. Ensure it has the BigQuery User role
  4. If the roles are missing, click Edit → Add Another Role → save
  5. Re-test the connection on the destination page
Error: DATASET_CREATION_FAILEDCause: The Detrics service account can’t create the dataset. This usually means the service account has job-level permissions but not project-level dataset creation rights.Fix:
  • Ensure the service account has the BigQuery User role at the project level (not just dataset level)
  • Alternatively, create the dataset manually in BigQuery Console and grant the service account access to it
Error: DATASET_NOT_FOUNDCause: The dataset was deleted from BigQuery after the destination was configured.Fix:
  • If you deleted the dataset intentionally, Detrics will recreate it on the next sync
  • If the dataset name changed, update the destination configuration
  • Re-test the connection on the destination page

​
Schema Migration Errors

These errors occur when Detrics can’t create or update table schemas in BigQuery.
Error: SCHEMA_TYPE_MISMATCHCause: A column’s data type in the existing BigQuery table doesn’t match what Detrics expects. This can happen if the table was manually modified in BigQuery.Fix:
  • Check the BigQuery table schema and compare it with the fields configured in Detrics
  • If you manually changed a column type in BigQuery, consider deleting the table and letting Detrics recreate it on the next sync
  • If the issue persists, run a Resync (Remove Data) to start fresh
Error: TABLE_NOT_MANAGEDCause: A table with the same name already exists in the dataset but wasn’t created by Detrics. Detrics won’t modify tables it didn’t create.Fix:
  • Rename the existing table in BigQuery, or
  • Change the table name or prefix in Detrics to avoid the conflict

​
Data Retrieval Errors

These errors occur when Detrics can’t fetch data from the platform API.
Error: DATA_RETRIEVAL_AUTH_ERRORCause: The OAuth token for the platform connection has expired or been revoked.Fix:
  1. Go to Workspace → Connections
  2. Find the connection and click Reconnect
  3. Re-authenticate with the platform
  4. Resume the transfer (if auto-paused)
Error: DATA_RETRIEVAL_RATE_LIMITCause: The platform’s API rate limit was exceeded. This can happen when you have many transfers syncing the same platform simultaneously, or during peak API usage periods.Fix:
  • Wait and retry — Detrics automatically retries with backoff, but persistent rate limiting may cause the sync to fail
  • Stagger transfer schedules so multiple transfers for the same platform don’t run at the same time
  • Reduce sync frequency if you’re hitting limits consistently
Error: DATA_RETRIEVAL_PERMISSIONCause: Access to one or more accounts was revoked on the platform side (e.g., removed from a Meta Business Manager, lost access to a GA4 property).Fix:
  • Verify your access to the affected accounts on the platform
  • If access was intentionally revoked, update the transfer to exclude those accounts
  • If access was accidentally revoked, re-grant it on the platform and retry the sync
Error: DATA_RETRIEVAL_API_ERRORCause: The platform API returned an unexpected error. This is usually a transient issue on the platform’s side (e.g., Meta Ads API outage, Google Ads service disruption).Fix:
Error: DATA_RETRIEVAL_TIMEOUTCause: The platform API took too long to respond. Common with very large accounts or complex queries.Fix:
  • The transfer will automatically retry on the next scheduled sync
  • If timeouts persist, consider reducing the table’s historical sync range or adding filters to reduce the data volume
  • For very large accounts, Detrics automatically chunks requests, but some queries may still hit platform-side timeouts
Error: DATA_RETRIEVAL_NO_DATACause: The platform returned no data for the requested accounts, date range, and fields. This is not necessarily an error — the account may have no activity in the requested period.Fix:
  • Verify the account has data in the requested date range by checking the platform directly
  • Check that the selected metrics and dimensions are valid for the account type
  • If the account is new, wait until it has data before syncing

​
Data Loading Errors

These errors occur when Detrics can’t write data to BigQuery.
Error: BQ_LOAD_TYPE_MISMATCHCause: The data returned by the platform doesn’t match the expected BigQuery column types. For example, a field expected to be numeric contains text values.Fix:
  • This is usually a transient issue caused by unexpected platform data. The next sync often resolves it
  • If it persists, check the specific field mentioned in the error and report it to Detrics support
Error: BQ_LOAD_QUOTA_EXCEEDEDCause: Your GCP project hit a BigQuery quota limit (e.g., maximum load jobs per day, maximum bytes loaded).Fix:
  • Check your BigQuery quotas in the GCP Console
  • Request a quota increase if needed
  • Stagger transfer schedules to spread load jobs over time
Error: BQ_LOAD_PERMISSION_DENIEDCause: The Detrics service account lost write access to the dataset.Fix:
  • Re-grant the BigQuery User role to the Detrics service account
  • Re-test the connection on the destination page

​
System Errors

Error: SYSTEM_LOCK_TIMEOUTCause: Another sync for the same transfer is already running. Detrics prevents concurrent runs to avoid data conflicts.Fix:
  • Wait for the current sync to finish
  • If a sync appears stuck, contact Detrics support
Error: SYSTEM_INTERNAL_ERRORCause: An unexpected error occurred in the Detrics pipeline.Fix:
  • The transfer will automatically retry on the next scheduled sync
  • If the error persists across multiple runs, contact Detrics support with the transfer ID and run ID

​
Getting Help

If you can’t resolve an error:
  1. Note the transfer ID and run ID from the transfer detail page
  2. Check the per-table error details in the run history for specific error messages
  3. Contact Detrics support via the Chat with Support button in the docs, or email [email protected]