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

# Troubleshooting Google BigQuery

> Fix common BigQuery connection, validation, and sync issues

Issues are grouped by where they appear: during setup, or after the connection is live.

## During setup

<AccordionGroup>
  <Accordion title="Validation fails right after granting access">
    **Cause:** IAM changes haven't propagated yet.

    **Fix:** Wait 2–5 minutes and click **Validate** again. Re-granting the role doesn't speed this up. If it still fails after 5 minutes:

    * Confirm the service account email exactly matches the one shown in the wizard.
    * Confirm you granted **BigQuery Data Viewer** — not BigQuery User or another role.
    * For dataset-level access, confirm you granted access on *every* dataset you entered.
  </Accordion>

  <Accordion title="Error: Access denied. Missing bigquery.dataViewer role">
    **Cause:** The service account can't read one of the datasets you entered.

    **Fix:** Run the grant command the wizard shows for that dataset, in the project that owns it. Wait 2–3 minutes, then click **Retry connection**. You can also continue with the datasets that did connect.

    To check whether a project-level binding was applied:

    ```bash theme={null}
    gcloud projects get-iam-policy YOUR_PROJECT_ID \
      --flatten="bindings[].members" \
      --filter="bindings.members:serviceAccount:SERVICE_ACCOUNT_EMAIL" \
      --format="table(bindings.role)"
    ```

    You should see `roles/bigquery.dataViewer`. For a dataset-level grant:

    ```bash theme={null}
    bq show --format=prettyjson YOUR_PROJECT_ID:YOUR_DATASET_NAME | grep -A5 "access"
    ```
  </Accordion>

  <Accordion title="Error: Dataset not found">
    **Cause:** The dataset name is misspelled, or it lives in a different GCP project than the one you entered.

    **Fix:** Check the spelling (dataset IDs are case-sensitive) and that the grant command ran in the project that owns the dataset.
  </Accordion>

  <Accordion title="Table blocked: Auxia requires date partitioning">
    **Cause:** The table isn't partitioned by day.

    **Fix:** Recreate the table partitioned by a date column:

    ```sql theme={null}
    CREATE TABLE `project.dataset.my_table_partitioned`
    PARTITION BY DATE(event_timestamp)
    AS SELECT * FROM `project.dataset.my_table`;
    ```
  </Accordion>

  <Accordion title="Table blocked: append required">
    **Cause:** The table adds more than 1 TB per day, which requires append-based reads — but it's a view, or doesn't support appends.

    **Fix:** Ingest from a native table with appends enabled rather than a view.
  </Accordion>

  <Accordion title="Table blocked: nested fields are too deep">
    **Cause:** `STRUCT` nesting exceeds the depth Auxia supports.

    **Fix:** Flatten the nested fields in BigQuery (for example, into a materialized table) and connect that instead.
  </Accordion>

  <Accordion title="Join blocked: pick columns with the same type">
    **Cause:** The join key columns have different data types (for example, `STRING` and `INT64`). Auxia doesn't cast join keys.

    **Fix:** Choose columns of the same type, or cast one of them in your source data first.
  </Accordion>

  <Accordion title="Unified preview returns no rows">
    **Cause:** Usually a join whose keys don't match on value or type, or a mapping that points at the wrong column.

    **Fix:** Check that join key values actually overlap between the two tables, then re-check the user ID and timestamp mappings.
  </Accordion>

  <Accordion title="Two configurations were created for one table">
    **Cause:** Going back to the mapping step and forward again creates a second, inactive copy.

    **Fix:** Enable only the configuration you reviewed. The other stays switched off and does nothing.
  </Accordion>
</AccordionGroup>

## After the connection is live

<AccordionGroup>
  <Accordion title="Nothing is syncing">
    **Cause:** The configuration is dormant — **Enable Later** was chosen at the end of the wizard — or it was paused.

    **Fix:** Go to **Configuration → Connections → Import Configurations** and enable the configuration. See [Monitoring with Data Health](/data-ingestion/concepts/monitoring).
  </Accordion>

  <Accordion title="Runs succeed but no data appears">
    **Cause:** The run starts before your data lands for the day. A run that finds nothing reports **Skipped**, not failed.

    **Fix:** Tell your Auxia contact when your tables are typically complete, so the data delay can be lengthened to match. Then request a backfill for the missed days.
  </Accordion>

  <Accordion title="Row counts doubled for a day">
    **Cause:** A day was re-read under the new-rows-only mode, which appends.

    **Fix:** Contact your Auxia point of contact. Full-refresh configurations are safe to re-run; incremental ones are not.
  </Accordion>

  <Accordion title="History before the connection date is missing">
    **Cause:** New connections are forward-looking.

    **Fix:** Contact your Auxia point of contact to load the date range you need.
  </Accordion>
</AccordionGroup>

## Still stuck?

Contact [support@auxia.io](mailto:support@auxia.io) or your Auxia point of contact. Include your connection name, the table, and a screenshot of the error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.