Database connection errors

Connection errors show up two places:

1. Dashboard → Site → Test connection — red error banner
2. Live voice sessions — AI tells the user “I can’t look that up right now”

Errors are surfaced from the adapter’s testConnection() / search() methods. They come back as plain text, so the exact message depends on the backend.

Universal causes

Cause	What to check
Wrong credentials	User, password, key — copy-paste again, check for whitespace
Wrong database/collection name	Case-sensitive; Users ≠ users
Firewall / IP allowlist	Our egress IPs at spelo.ai/security/ips
TLS misconfiguration	Server requires TLS, you set ssl: false (or vice versa)
Network outage	Try connecting from your laptop with the same credentials — does it work?
Permissions	The user exists but doesn’t have SELECT on the tables you listed

By adapter

Postgres

Error	Fix
password authentication failed for user X	Wrong password, or user doesn’t exist
connection refused	Firewall blocking our IPs, or DB not listening on the port
permission denied for relation X	GRANT SELECT ON TABLE X TO spelo_readonly;
relation "X" does not exist	Wrong source in collection config (case-sensitive)
SSL connection required	Set ssl: true in config
self signed certificate	Expected — set ssl: true (we pass rejectUnauthorized: false)

See Postgres adapter.

MySQL

Error	Fix
ER_ACCESS_DENIED_ERROR	Wrong user/password, or user host mismatch
ER_DBACCESS_DENIED_ERROR	User exists but no SELECT on the database
ETIMEDOUT	Firewall blocking
HANDSHAKE_NO_SSL_SUPPORT	ssl: true but server doesn’t have TLS
ER_BAD_FIELD_ERROR	A filterable_fields column doesn’t exist

See MySQL adapter.

MS SQL Server

Error	Fix
Login failed for user 'X'	Password wrong, or login/user not mapped to the DB
Cannot open server "X" requested by the login	Firewall rule
The TCP/IP connection to the host has failed	Wrong host/port, or SQL Browser disabled
SSL handshake failure	Set trustServerCertificate: true for self-signed

See MS SQL Server adapter.

MongoDB

Error	Fix
MongoServerError: bad auth	Wrong username/password
Authentication failed	User not authorized on target DB (check --authenticationDatabase)
ENOTFOUND	DNS issue with mongodb+srv:// URI
MongoTimeoutError: Server selection timed out	IP not in Atlas Network Access allowlist
MongoError: not authorized on X to execute command	User lacks read role on the DB

See MongoDB adapter.

Supabase

Error	Fix
JWSError / Invalid API key	Paste the anon or service key again
fetch failed	Wrong URL; must be https://xxxx.supabase.co
Empty results, no error	RLS policy denying read — check your policies

See Supabase adapter.

Firebase

Error	Fix
PERMISSION_DENIED: Missing or insufficient permissions	Service account lacks roles/datastore.viewer
FAILED_PRECONDITION: The query requires an index	Create the composite index via the link in the error
INVALID_ARGUMENT: Inequality filter property and first sort order must be the same	Firestore query limitation — simplify
Could not load the default credentials	You set useApplicationDefault: true but no ADC available

See Firebase adapter.

Airtable

Error	Fix
AUTHENTICATION_REQUIRED	Token missing or malformed (must start with pat)
NOT_FOUND	Wrong base ID or table name
INVALID_REQUEST_MISSING_FIELDS	A filterable_fields column doesn’t exist in the table
REQUEST_TOO_BIG	display_fields too wide — trim it

See Airtable adapter.

Google Sheets

Error	Fix
403 API key not valid	Key restriction blocks our IPs — add our IPs to allowlist
400 Unable to parse range	Tab name typo or contains a single quote
404 Requested entity was not found	Wrong spreadsheetId, or sheet not shared

See Google Sheets adapter.

Shopify

Error	Fix
401 Unauthorized	Wrong token, or app not installed
400 Storefront API access disabled	Shop plan doesn’t include Storefront API (contact Shopify)
No products returned	Ensure products are published, and unauthenticated_read_product_listings scope

See Shopify adapter.

WooCommerce

Error	Fix
401 Invalid authentication	Key/secret wrong (check for copy whitespace)
404 rest_no_route	WP permalinks set to “Plain” — switch to “Post name”
rest_cannot_view	Key permissions set to Write — create a new key with Read

See WooCommerce adapter.

REST / Webhook

Error	Fix
401	Bearer / API key wrong
404	Wrong path in source
429	Hitting target API’s rate limit
Signature mismatch (webhook only)	Wrong secret in config, or you hashed a parsed-and-reserialized body

See REST adapter or Webhook adapter.

Reading the actual error

Dashboard → Site → Data → Test connection → scroll to the error banner. The raw adapter error is shown (truncated to 500 chars). Click Show full to expand.

For production errors during live sessions, check Dashboard → Analytics → Query log — failures are logged with the adapter’s error message.

Still stuck?

Email support@spelo.ai with:

• The exact error text (copy-paste, not paraphrase)
• Your adapter type (postgres, mysql, etc.)
• Your collection config (redact credentials!)
• Whether curl / psql / mongosh with the same credentials works from your laptop