Connect Data

Troubleshooting connections

When a Test connection check fails, the root cause almost always falls into one of four categories: network reachability, TLS mismatch, credentials, or insufficient permissions.

Work through the diagnostic steps below.

1. Network reachability & timeouts

A connection test that runs for about 15 seconds and then says Connection failed: Could not reach the host — check the host, port, and network access. means the DataSquares server cannot open a TCP connection to that host and port. Test Connection always shows a short summary like this, not the database’s own error text.

Firewall & Security Groups — Ensure inbound traffic is permitted from the DataSquares server’s public IP address on the database port. Managed cloud databases (AWS RDS, Azure Database, Google Cloud SQL) deny inbound connections by default.
Non-standard ports — Verify whether your database engine uses a non-default port (e.g. AWS Aurora custom endpoints or Docker port mappings).
Microsoft Entra ID — A Fabric Warehouse source signs in through Microsoft Entra ID, so a DataSquares server you run yourself must also reach login.microsoftonline.com on port 443. When it cannot, the test says Microsoft Entra ID could not be reached to sign the service principal in; a request dropped without any answer instead runs until the connection time limit and fails with the general connection error. Either way the tenant ID, client ID and secret were never checked, so a new secret will not help.

A host DataSquares refuses

DataSquares connects only to publicly reachable addresses. Loopback (localhost, 127.0.0.1), private (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), link-local (169.254.0.0/16, which includes cloud metadata endpoints) and carrier-grade NAT (100.64.0.0/10) addresses are refused by design — and so is a host name that resolves to one — before any connection opens. There is no VPC peering and no SSH tunnel in the product.

What you see:

in the connection wizard: This host is not allowed: private and loopback addresses can’t be reached from DataSquares, or The host name could not be resolved. Check the spelling of the host.
from the API (POST /api/sources, POST /api/sources/test): a 400 whose message is Host not allowed or Host could not be resolved.

To connect a database on a private network, give it a publicly reachable endpoint with TLS on, and allowlist the DataSquares server’s IP address in its firewall or security group — as for Amazon Redshift.

2. TLS & SSL configuration

Mandatory TLS — Cloud database providers (Supabase, Neon, Azure SQL, PlanetScale) mandate encrypted connections. Verify that the TLS toggle is enabled.
Self-signed certificates — If your internal database uses a private or self-signed SSL certificate, enable the Trust self-signed certificate checkbox in the connection modal to allow the connection while maintaining wire encryption.
Certificate revocation & CN mismatches — Ensure the database hostname in the form matches the Common Name (CN) or Subject Alternative Name (SAN) on the server’s TLS certificate.
A SQL Server with no TLS — With Use SSL/TLS encryption ticked, a SQL Server that offers no encryption is refused before the login is sent, and the test says Connection failed: Secure connection failed — check the SSL/TLS settings. Install a certificate on the server, or untick TLS for that source. See SQL Server.

3. Authentication & credentials

Host-scoped user grants — Many SQL engines (such as MySQL and PostgreSQL) restrict user logins based on client origin IP (e.g. 'user'@'10.0.%' or pg_hba.conf client CIDR rules). Verify that the database user is permitted to log in from the DataSquares host IP.
Password rotations — If a previously working connection fails with authentication errors, click Edit on the source card in Data Sources to update the saved password or token.
Editing without rotating credentials — Leave credential fields empty to keep the stored values, choose Update Source, then Test on the source card. The connection form’s test uses the values currently entered in it.
Special characters in passwords — Characters like @, :, /, or % are handled automatically by the wizard’s driver layer, but verify credentials by testing with standard CLI tools if issues persist.
Expired client secrets — A Microsoft Entra ID client secret lasts the duration chosen when it was created. When a Fabric Warehouse test says Microsoft Entra ID did not sign the service principal in, create a new secret on the app registration and enter it in the source’s edit form.

4. Permissions & access roles

A connection that passes the test but displays no tables, or errors out during queries, is missing read grants:

Relational databases — Grant SELECT on target tables, and schema USAGE (for PostgreSQL, SQL Server, and Oracle) to the connection user.
Snowflake — User requires USAGE on the virtual warehouse, USAGE on the database and schema, and SELECT on tables, plus an assigned default role.
Google BigQuery — The Service Account must have the BigQuery Data Viewer and BigQuery Job User IAM roles.
Amazon Athena — IAM credentials must grant athena:StartQueryExecution, athena:GetQueryResults, AWS Glue catalog read permissions, S3 read permissions on source data, and S3 read/write permissions on the staging output bucket.
Databricks — The Personal Access Token (PAT) user requires CAN USE on the SQL Warehouse and SELECT on catalog schemas.
Fabric Warehouse — The service principal needs a role in the warehouse’s workspace (Viewer reads every warehouse in it) or a share of the warehouse, and the Fabric tenant settings must allow service principals (Service principals can use Fabric APIs). A share with no additional permissions reads only the tables granted to it with GRANT SELECT; a grant cannot narrow a Viewer. See Give the service principal a workspace role.

File upload, object store & API troubleshooting

File uploads:
- CSV files can be UTF-8, UTF-16 or Windows-1252 and use comma, semicolon, tab or pipe delimiters; all are detected automatically.
- A file can be up to 512 MB, and one import up to 1,000,000 rows. Split a larger file, or load it with a pipeline.
- Verify Excel workbooks are .xlsx format (legacy .xls is not supported).
- For JSON files, verify the array structure or specify the correct Records path (e.g. items or results.data).
Object stores (S3 / Azure / GCS):
- Ensure the bucket/container exists in the specified region.
- S3 IAM keys require s3:ListBucket and s3:GetObject.
- For multi-part partition folders, choose Import prefix in the Browse objects dialog.
Google Sheets:
- Share the spreadsheet, with Viewer access, with the client_email of the service-account key you pasted into the form.
REST APIs:
- Test the endpoint via curl to confirm JSON output.
- Verify headers (e.g. Authorization: Bearer <token>) and specify the Records path if the records array is nested inside a root object (it is detected automatically when the response has only one array).