# Common Issues

## Connection issues

<details>

<summary>"Connection refused" or "Cannot connect to MySQL server"</summary>

Your MySQL server is not reachable. Check:

1. **Hostname and port** — make sure you're using the correct hostname or IP address and port (default is 3306)
2. **Server is running** — verify your MySQL service is active
3. **Firewall/security group** — if your database is on AWS RDS, Google Cloud SQL, or behind a corporate firewall, you must whitelist Coupler.io's IPs: **52.21.222.113** and **35.170.113.181**
4. **Network connectivity** — test connectivity from your local machine using a MySQL client (e.g., `mysql -h hostname -u username -p`)

</details>

<details>

<summary>"Access denied for user" or authentication failure</summary>

Your credentials are incorrect or the user doesn't have the right permissions.

1. **Verify username and password** — double-check spelling and special characters
2. **Check user permissions** — the user must have SELECT permission on the database and table(s). Run this in MySQL to grant access:

   ```sql
   GRANT SELECT ON database_name.* TO 'username'@'%';
   ```
3. **Test credentials locally** — try connecting with the same credentials using a MySQL client from your computer
4. **Remote access** — if using `'username'@'localhost'`, change it to `'username'@'%'` to allow remote connections

</details>

<details>

<summary>IP whitelisting: "Your MySQL is blocking Coupler.io"</summary>

Your firewall or security group is rejecting Coupler.io's connection attempt.

1. **Add these IPs to your firewall:**
   * 52.21.222.113
   * 35.170.113.181
2. **AWS RDS** — edit your security group, add an inbound rule for TCP port 3306, source: 52.21.222.113/32 and 35.170.113.181/32
3. **Google Cloud SQL** — go to Connections > Public IP > Authorized networks, add both IPs with /32 CIDR
4. **Azure MySQL** — Server parameters > Connection security > Firewall rules, add both IPs
5. **Other providers** — check your hosting provider's documentation for adding IP allowlists

</details>

## Missing data

<details>

<summary>Exported data is missing rows or columns</summary>

1. **Check table permissions** — the user account must have SELECT permission on all columns and rows. Run:

   ```sql
   GRANT SELECT ON database_name.table_name TO 'username'@'%';
   ```
2. **Verify the table name** — make sure you selected the correct table (case-sensitive in some MySQL configurations)
3. **Filters applied** — check if any filters are active in your data flow that might be hiding rows
4. **View definition** — if exporting a view, verify the view's SQL is correct and returns the expected data

</details>

<details>

<summary>Data appears to be truncated or incomplete</summary>

Large tables or long-running queries can timeout.

1. **Apply filters** — filter by date range or status to reduce the volume of data (e.g., last 30 days instead of all history)
2. **Split into multiple flows** — create separate data flows for different date ranges or logical subsets of data
3. **Check query performance** — run the same query in MySQL Workbench or command line to confirm it completes quickly
4. **Contact support** — if your export consistently times out, reach out; we can investigate timeout settings

</details>

## Permission errors

<details>

<summary>"Permission denied" or "Table doesn't exist"</summary>

1. **Verify the database name** — MySQL database and table names are case-sensitive on Linux/Mac
2. **Check user privileges** — ensure the user has SELECT on the specific database:

   ```sql
   GRANT SELECT ON database_name.* TO 'username'@'%';
   FLUSH PRIVILEGES;
   ```
3. **Verify user host** — if the user is set up for `'username'@'localhost'`, change to `'username'@'%'` for remote access
4. **Test locally** — connect to MySQL locally with the same credentials and run `SELECT * FROM table_name;` to confirm access

</details>

## Data discrepancies

<details>

<summary>Data in my spreadsheet doesn't match what I see in MySQL</summary>

1. **Timestamp/timezone issues** — MySQL may store times in UTC; check if a timezone offset is causing mismatches
2. **Data type formatting** — JSON or complex data types may display as text strings; MySQL stores them as strings, so this is expected behavior
3. **Filters applied** — verify no filters are active in your data flow that would exclude rows
4. **Deleted or updated rows** — if your MySQL data changed between exports, the spreadsheet will reflect the latest export

</details>

<details>

<summary>Timestamps or dates are incorrect</summary>

1. **Timezone mismatch** — MySQL TIMESTAMP columns are stored in UTC; if your application uses a different timezone, convert in MySQL:

   ```sql
   SELECT CONVERT_TZ(timestamp_column, '+00:00', '-05:00') FROM table_name;
   ```
2. **DATETIME vs TIMESTAMP** — DATETIME stores raw values (no timezone), while TIMESTAMP converts to UTC; check which your table uses
3. **Destination formatting** — Google Sheets or Excel may display dates differently; check the cell format in your destination

</details>

## Rate limits

<details>

<summary>"Query timeout" or "The operation timed out"</summary>

Your query is taking too long to execute, likely due to table size or slow query performance.

1. **Apply filters** — restrict data by date range, status, or other criteria:

   ```
   WHERE created_at >= '2024-01-01' AND created_at < '2024-02-01'
   ```
2. **Export smaller batches** — split large tables into multiple data flows (e.g., one flow per month)
3. **Optimize your table** — ensure indexes exist on commonly filtered columns (created\_at, status, user\_id, etc.)
4. **Reduce frequency** — if scheduling hourly exports, consider switching to daily to reduce database load
5. **Contact support** — if timeouts persist on small queries, we can investigate further

</details>