# Troubleshoot connections

> What each connection error means and how to fix it, from a host sanda cannot reach to a table that has no rows attached.

When something goes wrong, the reason is almost always on the page. Look in three places:

- **The red note on the connection's Status tab.** It holds the last error. On a connection that is not syncing yet, it is labelled **Last attempt**.
- **The Timeline tab.** Each failed run carries its reason.
- **The message under the form** while you are adding a connection.

**Check status** asks sanda's managed sync again and refreshes what the page shows. Failure text often starts with which side of the pipe broke, such as the source or the destination, and what kind of failure it was, so read the first words.

## When you connect

Connecting happens when you press **Read schema** (or **Connect**, on a connection you are finishing). It signs in to the source and reads which tables it offers.

### Host errors before connecting

For a connector with a host field, such as a database, sanda checks the host you entered before it tries to connect, and refuses the ones that can never work. The messages say **database host** wherever they name the field. The message names what you typed and says what to put where.

| What the message says | What is wrong | Fix |
|---|---|---|
| The database host is blank | Nothing was entered | Enter the hostname or IP address the database answers on |
| The database host field has more than a hostname in it | A connection string or `user@host` was pasted | Put only the host in the host field. Put the port in the port field, and the username, password and database name in their own fields |
| That database host looks like host:port | `db.example.com:5432` in one field | Split it: the host in the host field, the port in the port field |
| … doesn't look like a hostname or IP address | Spaces, slashes or other characters no host can carry | Enter just the host |
| … means "this computer" | `localhost` or another loopback address | Use the address the database answers on from the internet |
| … is a private network address | An address such as `10.x.x.x`, `172.16.x.x` to `172.31.x.x` or `192.168.x.x` | Use the database's public hostname or IP, or route it through something the internet can reach |
| … has no domain, so it can only resolve inside your own network | A bare name such as `dbserver` | Use the full public hostname or IP |
| Names ending in .local only resolve inside private networks | A `.local`, `.internal`, `.lan` or similar name | Use the database's public hostname or IP |
| … does not resolve on the public internet | The name has a typo, or exists only inside your network | Check it for typos. Otherwise use the public hostname or IP |
| … resolves to … a private network address | The name points at an internal address | Give the database an address the internet can reach |

The same rules apply to an SSH tunnel host when the form offers one. See [Allowlist sanda's address](https://docs.sanda-os.com.au/connections/allowlist#hosts-sanda-can-reach).

### The connection is refused or times out

**What you see:** a message that sanda reached your database's network but nothing accepted the connection, and to check the port and that sanda's sync address is allowed through the firewall.

**Cause:** the host is right but the connection is being blocked, or the port is wrong.

**Fix:**

1. Check the port matches the one your database listens on (5432 for PostgreSQL, 3306 for MySQL and 1433 for SQL Server, unless you changed it).
2. Allow sanda's address through every firewall in the path. See [Allowlist sanda's address](https://docs.sanda-os.com.au/connections/allowlist).
3. Check the database accepts connections from outside its own machine, and that any rule restricting logins by address includes sanda's.

### Your database refused the username and password

**What you see:** **Your database refused the username and password sanda was given.**

**Fix:** re-enter the details. Check the username and password, that the login is allowed to connect from sanda's address (some databases restrict each login to certain addresses), and that the login can read the schemas you want. Nothing else about the connection needs changing.

If the connection failed before it ever connected, its page shows **Finish setting up this connection**. Press **Enter connection details** and try again. If you are still in the new connection flow, press **Retry connecting**.

### A hostname could not be resolved

**What you see:** a message that sanda could not resolve a hostname while setting the connection up.

**Cause:** the message tells you which of two situations you are in.

- **It says the host may be the problem.** If the database host is misspelled, or only resolves inside your own network, that is the cause. Correct the host. See the host errors above.
- **It says nothing you entered caused this.** sanda has checked your host and it resolves on the public internet, or the connector has no host field at all, so the fault is on sanda's side. Contact sanda support.

### The form says something is still needed

**What you see:** **Still needed:** and a list of fields under the form, or after you press the button, a message that the connector **still needs** those fields **before it can be connected**.

**Fix:** fill in the fields named. A required field hidden under **Advanced settings** opens the section by itself when it needs an answer.

### Other messages at this step

| Message | What to do |
|---|---|
| **There is nowhere to land rows yet. Provision a warehouse under Data · Warehouse first.** | Provision one. See [Provision your warehouse](https://docs.sanda-os.com.au/warehouse/provision) |
| **The warehouse this connection lands in has no credentials on file. Retry provisioning it under Data · Warehouse, or pick another destination.** | Retry provisioning from the warehouse's page, or choose another destination |
| **This connector needs its connection details before sanda can read its schema.** | The form was empty. Fill it in |
| **Only owners and admins can manage connections.** | Ask an owner or admin to do it |
| **sanda's managed sync isn't switched on yet, so nothing can move for this connection.** | Your setup is saved and sanda will finish wiring it up and be in touch. There is nothing to retry |

## When you choose streams

| Message | What to do |
|---|---|
| **Leave at least one stream on.** | Tick at least one table. To stop a connection, save its frequency as **Manual**, or delete it |
| **1 stream needs a cursor** or **needs a primary key** | Pick a cursor or key for each stream the message counts, or choose a mode that does not need one. See [Sync modes](https://docs.sanda-os.com.au/reference/sync-modes) |
| **sanda hasn't read this source's schema yet.** | The connection has not connected. Enter its details first |

If the picker cannot list the streams, it shows the reason with a **Close** or **Reload** button. The list comes from a live check of your source, so the causes are the same as when connecting. A table missing from the list is usually one the login cannot read, so check its permissions.

## When a run fails

A failed run shows **Sync failed** on the run panel, **Error** on the connection, and its reason in red. A run that ends without a stated reason says the last run failed and gave no reason. Press **Check status** to ask again, or open the run in the **Timeline** tab.

| What you see | What it means | What to do |
|---|---|---|
| The source refused the login, or the connection is refused | Your credentials or firewall changed since setup | Check the source. See the sections above. A rotated password cannot be edited in the console, so contact sanda support |
| **This source already carries the bookkeeping columns sanda's own loading adds** | The source is a warehouse that another loader has already filled, and its loading columns clash with sanda's | Open **Edit streams** and save the selection again. That leaves the clashing columns out, and the next sync goes through |
| A failed run while the **Warehouse** page shows **At a limit: syncs are paused and queries are throttled until it comes back under, or the limit moves.** | The warehouse reached a storage or compute limit, and sanda stops loading until it is back under | Raise the limit or clear space under **Data · Warehouse**. See [Usage and suspension](https://docs.sanda-os.com.au/warehouse/usage-and-suspension) |
| **This workspace's warehouse is suspended** | The month's spend reached your budget, so syncs wait | An owner or admin resumes it under **Settings · Plan & budget**, once the budget is raised or the month is back under it |
| **This workspace is frozen: its free trial credit ran out** | A trial spends its credit and then waits for a paid edition | An owner or admin asks to move to an edition under **Settings · Plan & budget**. See [Free trial](https://docs.sanda-os.com.au/billing/trial) |
| A note that the run was cancelled before it finished | The run was stopped | Press **Sync now** |
| **sanda lost track of this run** | A newer run started before sanda saw this one finish | Look at the newer run. Nothing to fix |
| **… no longer has this connection, so nothing is running** | The connection is gone from sanda's managed sync | Delete the connection and add it again, or contact sanda support first if you want the same tables |

Two states are not failures:

- **Rate limited** on a stream means the source asked sanda to wait. The run retries at the time shown.
- A run that seems stuck may be launching. Every run starts a fresh connector, which can take a minute or two before the first rows move. If rows stop for a minute and a half or longer mid-run, the source may be slow or rate limiting, or the run may have hung. Give it time, then contact sanda support if it does not move.

If a run still reads **running** after twelve hours, press **Check status** to settle it.

## Rows landed, but cannot be read

Rows can arrive in your warehouse and still not be readable, because sanda makes each landed table readable after a run, and something can be in the way.

### Rows landed, but sanda could not attach

**What you see:** the connection reads **Error**, with a message that begins **Rows landed, but sanda could not attach** and the number of tables, followed by why.

**Cause:** sanda could not make the new copy of a table readable at its usual name, `raw.<connection>__<stream>`. Common reasons the message gives:

- **Something else with that name is already there.** A view, or a table sanda did not make, already has that name in `raw`. Rename or drop it.
- **A view of yours depends on a column the source no longer sends.** The message names the view and the column. sanda will not drop your view for you. Drop or redefine it.

**Fix:** remove the thing in the way, then press **Check status** on the connection. sanda retries and clears the message. Otherwise the next sync attaches the tables.

### A table has no rows attached right now

**What you see:** a question, report or view over a landed table fails with **… has no rows attached right now: its sync is finalising, or the last sync could not be attached. Try again in a few minutes.**

**Cause:** a run that replaces a table swaps in the new copy at the end, and sanda attaches that copy when it next checks the run. Until then, sanda returns this message rather than an empty answer, so a report is never sent empty.

**Fix:** wait, or press **Check status** on the connection, which attaches the copy at once. If you have the connection open while a run finishes, this happens by itself. For a scheduled run that nobody is watching, sanda's own check runs every 15 minutes. If the message persists, look for **Rows landed, but sanda could not attach** on the connection.

A scheduled report that reads a table right after its sync can meet this window. Schedule the report a little later than the sync. See [Report delivery](https://docs.sanda-os.com.au/reports/delivery).

### The connection says sanda repaired something

After a failed run, sanda sometimes repairs a problem in the landing tables itself and says what it did on the connection: that it moved tables out of the way, detached a table so a column's type could change, or started the sync again. If the message says to run the sync again, press **Sync now**.

If it says a view of yours still reads tables that sanda could not redefine, rebuild that view under **Data · Modelling**, then run the sync again.

## When data looks wrong

| You see | Likely cause |
|---|---|
| **Last sync** is older than you expect | The frequency is **Manual**, the connection is in error, or the workspace is suspended. Check **Status**, and the **Next sync** figure |
| **Next sync** shows a different time from the one you set | It is written in the zone the frequency under it names, which may not be yours. An older schedule kept in UTC also moves by an hour when the clocks change. See [Sync schedules](https://docs.sanda-os.com.au/connections/schedules#time-zones-and-daylight-saving) |
| **Rows synced** is far bigger than your tables | It totals every run, and a full refresh counts the whole table again each time |
| Deleted rows are still in a table | The stream is incremental, and a cursor cannot see a deletion. See [Sync modes](https://docs.sanda-os.com.au/connections/sync-modes#how-to-choose) |
| A table has several copies of the same row | The stream is on **Full refresh · Append** or **Incremental · Append**, which keep earlier versions. Choose a deduplicated mode to keep one row per key |
| A column you expected is missing | A column that the source does not send, or that sanda leaves out because it clashes with its loading columns |
| A CSV replace fails, naming a view that reads a column of the table | A view of yours under **Data · Modelling** reads a column the new file drops or retypes. See [Load a CSV](https://docs.sanda-os.com.au/connections/upload-a-csv#replacing-a-table-that-is-in-use) |

## Still stuck

Raise a ticket under **System · Support**. Include the connection's name, the time and the run number from the **Timeline** tab, and the message exactly as the page shows it. Failures where the message says the fault is on sanda's side, and anything about changing a connection's sign-in details, go to sanda support.

:::links
- [Allowlist sanda's address](https://docs.sanda-os.com.au/connections/allowlist): The usual fix for network errors.
- [Monitor syncs](https://docs.sanda-os.com.au/connections/monitor-syncs): Where each message appears.
- [Help and troubleshooting](https://docs.sanda-os.com.au/help/troubleshooting): Problems beyond connections.
:::