> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/destinations/categories/database/postgresql/common-issues.md).

# Common Issues

## Connection issues

<details>

<summary>Coupler.io can't connect to my PostgreSQL server</summary>

This usually means the host, port, or credentials are wrong — or your database server is blocking the connection.

Things to check:

* Make sure the **host**, **port**, **database name**, **username**, and **password** are all correct
* Confirm your PostgreSQL instance is accessible from the internet (or at least from Coupler.io's IPs)
* If your server uses IP allowlisting or a firewall, add both Coupler.io IPs to the allowlist:
  * `34.123.243.115`
  * `34.170.96.92`
* If you're connecting to **Supabase**, use the connection string details from **Settings → Database** in your Supabase dashboard, and make sure you're using the correct connection mode (Session or Transaction pooler)

{% hint style="warning" %}
Some cloud-hosted PostgreSQL providers (e.g., AWS RDS, Google Cloud SQL) require you to explicitly enable public access or configure VPC rules. Check your provider's network settings if the connection keeps failing.
{% endhint %}

</details>

<details>

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

A timeout during the run (not at the credential step) often indicates the database server is under load, or the query is taking too long for very large datasets.

* Try running the data flow again — transient timeouts often resolve themselves
* If the issue persists, check your PostgreSQL server's resource usage (CPU, memory, connections)
* Consider splitting large data flows into smaller sources or filtering data at the source level

</details>

## Data issues

<details>

<summary>Data flow fails with a column name error</summary>

PostgreSQL enforces a **63-character limit** on column names. If your source data has field names longer than 63 characters, the data flow will fail.

This is a known issue with sources like **Facebook (Meta) Ads** and **Stripe**, which sometimes produce long field names.

To fix this:

* Use the **Transformations** step in your data flow to rename the affected columns to shorter names before they reach PostgreSQL
* Be careful when editing transformations — changes are saved automatically without a confirmation prompt, so double-check before navigating away

{% hint style="danger" %}
Transformation changes in Coupler.io save automatically. Accidental edits can change your column structure without warning. Review your transformation settings carefully if your data flow suddenly starts failing.
{% endhint %}

</details>

<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), PostgreSQL won't know about them and the run may fail.

To fix this, manually `ALTER TABLE` in PostgreSQL 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 deleting 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>

## Permission errors

<details>

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

The PostgreSQL user you connected with doesn't have enough privileges. Make sure the user has:

* **CREATE** privilege on the target database
* **CREATE** privilege on the target schema
* **INSERT** privilege on the target table

You can grant these with:

```sql
GRANT CREATE ON DATABASE your_database TO your_user;
GRANT CREATE ON SCHEMA your_schema TO your_user;
GRANT INSERT ON TABLE your_schema.your_table TO your_user;
```

{% hint style="info" %}
If you want Coupler.io to create new schemas and tables automatically, the user needs CREATE at both the database and schema level — not just INSERT on an existing table.
{% endhint %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.coupler.io/destinations/categories/database/postgresql/common-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.