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.
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:
- 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).
- Allow sanda's address through every firewall in the path. See Allowlist sanda's address.
- 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 |
| 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 |
| 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 |
| 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 |
| 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.
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 |
| 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 |
| 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 |
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.
Something unclear or out of date? Tell us, and we will fix the page.