Data Source Troubleshooting

Data source connection not working? This guide covers the most common issues and how to fix them.

Connection Failures

Connection Timeout

Symptom: "Connection timed out" or the test hangs for 30+ seconds and fails.

Causes and Fixes:

• Wrong host or port — double-check the hostname and port number. Common defaults: PostgreSQL 5432, MySQL 3306, MongoDB 27017.
• Firewall blocking — your database may be behind a firewall that blocks external connections. Whitelist clariBI's IP range (contact support for current IPs).
• VPN/private network — if the database is on a private network, clariBI cannot reach it directly. Consider setting up a secure tunnel or using a database replication to a publicly accessible instance.

Authentication Failed

Symptom: "Authentication failed" or "Access denied."

Causes and Fixes:

• Wrong credentials — verify username and password. Test them by connecting directly with a database client (psql, mysql, etc.).
• User not allowed from remote host — some databases restrict connections by source IP. Ensure the user can connect from clariBI's IP.
• Expired password — some databases enforce password expiry policies. Reset the password and update it in clariBI.
• OAuth token expired — for Google/Meta/Jira connections, tokens can expire. Reconnect the data source to refresh the token.

SSL/TLS Errors

Symptom: "SSL connection error" or "certificate verification failed."

Causes and Fixes:

• SSL not enabled in clariBI — toggle the SSL option on in the connection form.
• SSL required but not configured on server — ensure your database server has SSL enabled.
• Self-signed certificates — clariBI may not accept self-signed certs by default. Contact support for options.

Sync Failures

Sync Stuck or Taking Too Long

Symptom: sync shows "in progress" for hours.

Causes and Fixes:

• Large dataset — initial syncs on very large databases can take time. Let it complete or narrow the sync scope to specific tables.
• Network instability — a dropped connection during sync can stall it. Cancel the sync and retry.
• Database under heavy load — clariBI's read queries may time out if the database is overloaded. Try syncing during off-peak hours.

Partial Data or Missing Tables

Symptom: not all tables or columns appear after sync.

Causes and Fixes:

• Insufficient permissions — the database user may not have SELECT access on all tables. Grant permissions: GRANT SELECT ON ALL TABLES IN SCHEMA public TO your_user;
• Schema not specified — if your tables are in a non-default schema, specify it in the connection settings.
• Views not included — by default, clariBI syncs tables. Views may need explicit inclusion.

File Upload Issues

CSV Parsing Errors

Symptom: "Could not parse file" or garbled data in preview.

Causes and Fixes:

• Wrong encoding — save the file as UTF-8. In Excel: Save As > CSV UTF-8.
• Inconsistent delimiters — mixed comma/semicolon/tab delimiters confuse the parser. Use one delimiter throughout.
• Unquoted fields with commas — if your data contains commas, fields should be wrapped in double quotes.
• No header row — clariBI expects the first row to be column names.

Excel Issues

• Merged cells — unmerge all cells before uploading.
• Formulas — clariBI imports calculated values, not formulas. If a cell shows an error (#REF!, #N/A), the import will include the error text.
• Multiple sheets — each sheet is imported separately. Check that you selected the right sheet in the preview.

PDF OCR Issues

• Scanned image quality — low-resolution scans produce poor OCR results. Use 300 DPI or higher.
• Complex layouts — multi-column layouts, watermarks, and decorative elements confuse OCR.
• Handwriting — OCR works best with printed text. Handwritten content is not reliably extracted.

API Source Issues

Empty Response

• Verify the endpoint URL is correct by testing it in a browser or with curl
• Check that the API key is valid and has appropriate permissions
• Ensure the API is not returning an error wrapped in a 200 OK response

Rate Limiting

• Some APIs limit request frequency. clariBI respects standard rate limit headers.
• If you hit rate limits during sync, the sync will retry with backoff. Large syncs may take longer.

General Tips

• Check the sync log — click on a data source to see its sync history with timestamps and error details.
• Test with a minimal case — for database issues, try connecting to a simple table with a few rows first.
• Update credentials proactively — if you rotate passwords or API tokens, update them in clariBI immediately.
• Contact support — if you have tried everything here and the issue persists, contact clariBI support with the data source ID and error message.