# Common Issues

## Connection issues

<details>

<summary>"Access Denied: BigQuery Permission denied while getting Drive credentials"</summary>

This error occurs when Coupler.io's service account doesn't have permission to access your BigQuery datasets or the destination Google Sheet.

**Fix:**

1. Copy the service account email from the error message (e.g., `coupler-io@project-name.iam.gserviceaccount.com`)
2. In Google Cloud Console, go to your BigQuery dataset → **Sharing** → **Add Principal**
3. Paste the service account email and grant it the **BigQuery Data Viewer** role
4. If writing to Google Sheets, share the sheet directly with the same service account email
5. Run the data flow again

</details>

<details>

<summary>"User does not have bigquery.jobs.create permission in project"</summary>

Your Service Account is missing the **BigQuery Job User** role, which is required to execute queries.

**Fix:**

1. Go to Google Cloud Console → **IAM & Admin** → **Roles**
2. Find your Service Account
3. Click **Edit** and add the **BigQuery Job User** role
4. Save and retry the data flow

</details>

<details>

<summary>"Sorry, we cannot connect to Cloud Services without a project ID"</summary>

The JSON key file you uploaded is missing required fields or is corrupted.

**Fix:**

1. Download a new Service Account JSON key from Google Cloud Console
2. Delete the old connection in Coupler.io
3. Re-upload the new JSON key
4. Retry the data flow

</details>

## Missing data

<details>

<summary>Query returns no results or fewer rows than expected</summary>

Your SQL query may be filtering out data incorrectly or referencing the wrong table.

**Fix:**

1. Run the same SQL query directly in BigQuery's web UI
2. Check your `WHERE` clause — verify dates and filter conditions are correct
3. Verify the table name includes the full path: `project_id.dataset_name.table_name`
4. Check for typos in column names (BigQuery is case-sensitive for column references)
5. If using date filters, confirm the date range is not excluding today's data

</details>

<details>

<summary>Data duplicates when using "Append" mode</summary>

When appending data, Coupler.io will add new rows even if they already exist in the sheet.

**Fix:**

1. If you need to replace all data each run, use **Replace** mode instead of **Append**
2. If using **Append**, filter your query with a date range to only fetch new/updated records since the last run
3. Example: `WHERE updated_at > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)`

</details>

## Permission errors

<details>

<summary>"Access Denied: Project X: User does not have [permission] in project"</summary>

The service account has the wrong permissions or is trying to access a dataset it doesn't have access to.

**Fix:**

1. Verify the Service Account has **BigQuery Data Viewer** role on the specific dataset (not just the project)
2. If querying multiple datasets, the service account needs viewer access to all of them
3. Go to each dataset → **Sharing** → add the service account with **BigQuery Data Viewer** role
4. Retry the data flow

</details>

<details>

<summary>"Files /gdrive/id/... not found" when writing to Google Sheets</summary>

Coupler.io cannot find your destination Google Sheet.

**Fix:**

1. Verify the sheet URL is correct and the sheet is in your Google Drive
2. Share the sheet explicitly with the service account email from the error
3. Make sure the sheet is not in a shared drive owned by someone else without your access
4. Try creating a new, simple test sheet in your Drive and retry

</details>

## Data discrepancies

<details>

<summary>Data in Coupler.io import doesn't match BigQuery</summary>

The query may be returning incorrect data, or the destination range is too small.

**Fix:**

1. Run your SQL query directly in BigQuery to confirm the expected result
2. If using a cell range (e.g., A1:B10) in **Replace** mode, verify the range is large enough to hold all results
3. Check for data type mismatches (e.g., numbers stored as strings)
4. If the query is correct in BigQuery but wrong in Coupler.io, contact support with your query and a screenshot of both

</details>

<details>

<summary>Only part of the data shows up in Google Sheets</summary>

You may have used a cell range that's too small, or the append range is incorrect.

**Fix:**

1. In **Replace** mode, use a large range or just specify the starting cell (e.g., A1) to auto-fit
2. In **Append** mode, set the range to an empty row where you want data to start (e.g., A2 for row 2)
3. Avoid specifying exact ranges like A1:B10 if your data might exceed that size

</details>

## Rate limits

<details>

<summary>Queries are slow or timing out</summary>

Large queries or scans can take time in BigQuery, especially if scanning many bytes.

**Fix:**

1. Optimize your SQL: select only needed columns (avoid `SELECT *`)
2. Add WHERE clauses to filter by date or other dimensions early
3. Break very large queries into smaller, separate data flows
4. Check BigQuery's query performance in the web UI to identify slow operations
5. Consider materializing frequently-used aggregations as BigQuery views or tables

</details>

<details>

<summary>"Quota exceeded" or billing errors</summary>

Your GCP project may have hit a quota limit or billing is not enabled.

**Fix:**

1. Verify billing is enabled for your GCP project (go to **Billing** in Google Cloud Console)
2. Check your GCP quotas: **Quotas** → filter for "BigQuery"
3. If you've hit a quota, request a quota increase
4. Review your BigQuery usage in **BigQuery Reports** to identify expensive queries
5. Reduce query volume or optimize query efficiency to lower costs

</details>