# Common Issues

## Connection issues

<details>

<summary>OAuth authorization fails or returns an error</summary>

This usually means something went wrong during the Snowflake OAuth flow. Common causes:

* Your Snowflake account URL is incorrect or the account is inactive
* Your browser is blocking pop-ups or third-party cookies required for the OAuth redirect
* The Snowflake user you're logging in with doesn't have a default role assigned

Things to try:

* Ensure you're logging into the correct Snowflake account
* Allow pop-ups for Coupler.io in your browser settings
* Check that your Snowflake user has a default role set (e.g., `SYSADMIN` or a custom role with the required privileges)
* Try disconnecting and reconnecting the Snowflake account in Coupler.io

</details>

<details>

<summary>Data flow fails because the warehouse is suspended</summary>

Snowflake warehouses can be suspended (paused) to save credits. If the warehouse assigned to your user or role is suspended and auto-resume is disabled, Coupler.io won't be able to execute queries.

To fix this:

* Enable **auto-resume** on the warehouse so it starts automatically when Coupler.io connects
* Alternatively, manually resume the warehouse in the Snowflake console before running the data flow

{% hint style="info" %}
You can enable auto-resume with: `ALTER WAREHOUSE your_warehouse SET AUTO_RESUME = TRUE;`
{% endhint %}

</details>

<details>

<summary>Connection times out during the data flow run</summary>

A timeout during the run (not at the OAuth step) can indicate the warehouse is too small for the data volume, or that Snowflake is experiencing transient issues.

* Try running the data flow again — transient timeouts often resolve themselves
* If the issue persists, consider scaling up the warehouse size temporarily for the initial load
* Check the Snowflake query history in the Snowflake console for more details on what failed

</details>

## Data issues

<details>

<summary>Append mode breaks after a source schema change</summary>

When using Append mode, Coupler.io writes new rows into the existing table structure. If your source adds new columns (for example, a new metric in your ad platform), Snowflake won't know about them and the run may fail.

To fix this, manually `ALTER TABLE` in Snowflake to add the new column(s) before the next run. After that, Coupler.io will populate them normally.

</details>

<details>

<summary>Data types are wrong in the destination table</summary>

Coupler.io detects and enforces column types automatically. However, if the table already exists with different column types from a previous run or manual creation, there can be a mismatch.

* If you're using **Replace** mode, try dropping the existing table and letting Coupler.io recreate it cleanly on the next run
* If you're using **Append** mode, check that the existing table's column types match what Coupler.io is trying to write

</details>

<details>

<summary>Data flow fails with an identifier or naming error</summary>

Snowflake treats unquoted identifiers as uppercase by default. If your table or column names contain mixed case or special characters, they may need to be quoted in Snowflake.

* Let Coupler.io create the table from scratch (using Replace mode on a new table) to avoid naming conflicts
* If you pre-created the table manually, make sure the column names match exactly what Coupler.io expects — check case sensitivity

</details>

## Permission errors

<details>

<summary>Permission denied when creating a schema or table</summary>

The Snowflake role associated with your connected account doesn't have enough privileges. Make sure the role has:

* **USAGE** on the target warehouse
* **USAGE** on the target database
* **USAGE** and **CREATE TABLE** on the target schema
* **INSERT** on the target table

You can grant these with:

```sql
GRANT USAGE ON WAREHOUSE your_warehouse TO ROLE your_role;
GRANT USAGE ON DATABASE your_database TO ROLE your_role;
GRANT USAGE ON SCHEMA your_database.your_schema TO ROLE your_role;
GRANT CREATE TABLE ON SCHEMA your_database.your_schema TO ROLE your_role;
GRANT INSERT ON ALL TABLES IN SCHEMA your_database.your_schema TO ROLE your_role;
```

{% hint style="info" %}
If you want Coupler.io to create new tables automatically, the role needs CREATE TABLE on the schema — not just INSERT on existing tables.
{% endhint %}

</details>