> ## Documentation Index
> Fetch the complete documentation index at: https://support.detrics.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors and how to resolve them

<Info>**Last updated:** March 18, 2026</Info>

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.

<AccordionGroup>
  <Accordion title="Permission Denied. Can't access the GCP project">
    **Error:** `DATASET_PERMISSION_DENIED`

    **Cause:** The Detrics service account doesn't have the required IAM roles in your GCP project.

    **Fix:**

    1. Go to [Google Cloud Console → IAM](https://console.cloud.google.com/iam-admin/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
  </Accordion>

  <Accordion title="Dataset Creation Failed">
    **Error:** `DATASET_CREATION_FAILED`

    **Cause:** 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
    * On a [Least-Privilege Access](/bigquery/least-privilege-access) destination this is expected. Detrics never creates the dataset; pre-create it yourself
  </Accordion>

  <Accordion title="Dataset Not Found">
    **Error:** `DATASET_NOT_FOUND`

    **Cause:** 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
  </Accordion>
</AccordionGroup>

## Schema Migration Errors

These errors occur when Detrics can't create or update table schemas in BigQuery.

<AccordionGroup>
  <Accordion title="Schema Type Mismatch">
    **Error:** `SCHEMA_TYPE_MISMATCH`

    **Cause:** 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
  </Accordion>

  <Accordion title="Table Not Managed by Detrics">
    **Error:** `TABLE_NOT_MANAGED`

    **Cause:** 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
  </Accordion>
</AccordionGroup>

## Data Retrieval Errors

These errors occur when Detrics can't fetch data from the platform API.

<AccordionGroup>
  <Accordion title="Authentication Error. Token Expired">
    **Error:** `DATA_RETRIEVAL_AUTH_ERROR`

    **Cause:** The OAuth token for the platform connection has expired or been revoked.

    **Fix:**

    1. Go to [**Workspace → Connections**](https://app.detrics.io/datasources)
    2. Find the connection and click **Reconnect**
    3. Re-authenticate with the platform
    4. Resume the transfer (if auto-paused)
  </Accordion>

  <Accordion title="Rate Limit Hit">
    **Error:** `DATA_RETRIEVAL_RATE_LIMIT`

    **Cause:** 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
  </Accordion>

  <Accordion title="Permission Revoked">
    **Error:** `DATA_RETRIEVAL_PERMISSION`

    **Cause:** 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
  </Accordion>

  <Accordion title="Platform API Error">
    **Error:** `DATA_RETRIEVAL_API_ERROR`

    **Cause:** 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:**

    * Wait for the platform to recover and retry the sync
    * Check the platform's status page for any ongoing outages
    * If the error persists, check the specific error message for details
  </Accordion>

  <Accordion title="Request Timeout">
    **Error:** `DATA_RETRIEVAL_TIMEOUT`

    **Cause:** 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
  </Accordion>

  <Accordion title="No Data Available">
    **Error:** `DATA_RETRIEVAL_NO_DATA`

    **Cause:** 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
  </Accordion>
</AccordionGroup>

## Data Loading Errors

These errors occur when Detrics can't write data to BigQuery.

<AccordionGroup>
  <Accordion title="Type Mismatch During Load">
    **Error:** `BQ_LOAD_TYPE_MISMATCH`

    **Cause:** 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
  </Accordion>

  <Accordion title="BigQuery Quota Exceeded">
    **Error:** `BQ_LOAD_QUOTA_EXCEEDED`

    **Cause:** Your GCP project hit a BigQuery quota limit (e.g., maximum load jobs per day, maximum bytes loaded).

    **Fix:**

    * Check your [BigQuery quotas](https://console.cloud.google.com/iam-admin/quotas) in the GCP Console
    * Request a quota increase if needed
    * Stagger transfer schedules to spread load jobs over time
  </Accordion>

  <Accordion title="BigQuery Permission Denied">
    **Error:** `BQ_LOAD_PERMISSION_DENIED`

    **Cause:** 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
  </Accordion>
</AccordionGroup>

## System Errors

<AccordionGroup>
  <Accordion title="Lock Timeout">
    **Error:** `SYSTEM_LOCK_TIMEOUT`

    **Cause:** 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
  </Accordion>

  <Accordion title="Internal Error">
    **Error:** `SYSTEM_INTERNAL_ERROR`

    **Cause:** 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
  </Accordion>
</AccordionGroup>

## 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 [support@detrics.io](mailto:support@detrics.io)