How to Read This Guide
Each error entry follows this format:
- Error Message -- the exact text you see in clariBI
- When It Appears -- the action that triggers it (connection test, sync, etc.)
- Cause -- what is going wrong
- Fix -- step-by-step resolution
Errors are grouped by category. Use your browser's search (Ctrl+F / Cmd+F) to find a specific error message.
Connection Errors
"Connection refused"
When It Appears: Testing a database connection (PostgreSQL, MySQL, SQL Server)
Cause: The database server is not accepting connections on the specified host and port. Either the server is down, the port is wrong, or a firewall is blocking the connection.
Fix: 1. Verify the hostname and port are correct. 2. Confirm the database server is running. 3. Check that your firewall allows inbound connections from clariBI's IP addresses. Contact support for the current IP list. 4. If using a cloud database (AWS RDS, Google Cloud SQL, Azure), check the security group or authorized networks settings.
"Connection timed out"
When It Appears: Testing a database connection
Cause: clariBI can reach the host but the connection attempt is not completing. Usually caused by a firewall that silently drops packets rather than rejecting them.
Fix: 1. Verify the host is reachable from the public internet (or configure the appropriate network access). 2. Check firewall rules -- a silent drop (no reject) causes timeouts rather than "connection refused" errors. 3. Try increasing the connection timeout in the data source advanced settings (default: 30 seconds).
"Host not found" / "Name resolution failed"
When It Appears: Testing any connection
Cause: The hostname cannot be resolved to an IP address via DNS.
Fix:
1. Double-check the hostname for typos.
2. If using a private hostname, ensure it is resolvable from the public internet. Internal DNS names (like db.internal.company.local) will not work unless you configure a VPN or SSH tunnel.
3. Try using the IP address directly instead of a hostname.
Authentication Errors
"Authentication failed" / "Login failed"
When It Appears: Testing a database connection or API source
Cause: The username, password, or token is incorrect.
Fix: 1. Re-enter the credentials carefully (watch for copy-paste whitespace). 2. Verify the user exists in the database and has login privileges. 3. For API sources, check that the token has not expired. 4. For OAuth sources, try re-authorizing the connection.
"Access denied for user"
When It Appears: After successful connection, during query execution
Cause: The user authenticated successfully but does not have permission to access the specified database or table.
Fix:
1. Grant the user SELECT access to the required database/tables. See the SQL examples in Connecting PostgreSQL, MySQL, and SQL Server.
2. For MySQL, ensure the user has access from the connecting host ('%' or the specific clariBI IP).
"SSL required" / "SSL connection error"
When It Appears: Testing a database connection
Cause: The database server requires SSL but the connection was attempted without it, or the SSL configuration is mismatched.
Fix:
1. Enable SSL in the data source settings.
2. If the server uses a self-signed certificate, upload the CA certificate or enable "Trust Server Certificate."
3. For PostgreSQL, try setting SSL mode to require first, then verify-ca if the server demands it.
"OAuth token expired" / "Invalid refresh token"
When It Appears: During sync of OAuth-connected sources (Google Analytics, Google Sheets, Jira)
Cause: The refresh token stored by clariBI is no longer valid. This can happen if you revoked access from the third-party service's settings, or if the token exceeded its maximum lifetime.
Fix: 1. Go to the data source settings. 2. Click Reauthorize. 3. Complete the OAuth flow again to generate a new refresh token.
Sync Errors
"Query execution timeout"
When It Appears: During data sync
Cause: A database query took too long to return results. This happens with very large tables or complex queries.
Fix: 1. Increase the query timeout in the data source advanced settings. 2. Use table/schema selection to exclude large tables you do not need. 3. Add database indexes on frequently queried columns. 4. Consider syncing at off-peak hours when the database is under less load.
"Rate limit exceeded" / "429 Too Many Requests"
When It Appears: During API source sync
Cause: The external API is rejecting requests because you have exceeded its rate limit.
Fix: 1. Increase the request delay in the data source settings (under Advanced > Request Delay). 2. Reduce the sync frequency (e.g., from hourly to daily). 3. Check the API provider's documentation for rate limit details and adjust accordingly.
"Response parsing error" / "Invalid JSON response"
When It Appears: During API source sync
Cause: The API returned a response that clariBI could not parse. The response may not be valid JSON, or the data path is pointing to the wrong location.
Fix: 1. Test the API manually (using curl or Postman) to see the actual response. 2. Verify the data path in the data source settings points to the correct location in the JSON response. 3. Check if the API returns different response formats based on error conditions.
"File not found"
When It Appears: During sync of Google Drive or file-based sources
Cause: The file has been moved, renamed, or deleted from its original location.
Fix: 1. For Google Drive sources, check that the file still exists and that you still have access. 2. For uploaded files, re-upload the file. 3. If the file was moved, disconnect and reconnect the source with the new location.
"Maximum rows exceeded"
When It Appears: During sync
Cause: The data source returned more rows than your plan allows for a single sync operation.
Fix: 1. Use table/schema selection to narrow the data being synced. 2. Apply a date filter to sync only recent data. 3. Upgrade your plan for higher row limits.
Data Quality Errors
"Column type mismatch"
When It Appears: During sync when the source schema has changed
Cause: A column that was previously numeric is now returning text (or vice versa). This often happens when someone modifies a Google Sheet or changes a database column type.
Fix: 1. Go to the data source settings and review the column mappings. 2. Update the column data type to match the new source format. 3. Re-sync the data source.
"Duplicate column names"
When It Appears: During initial connection or after a schema change
Cause: Two or more columns have the same name. This often happens in CSV or Excel files with duplicate headers.
Fix: 1. Edit the source file to give each column a unique name. 2. Re-upload or re-sync the data source.
"Empty dataset"
When It Appears: After sync completes
Cause: The sync completed successfully but no rows were returned. The table may be empty, the query may be too restrictive, or a filter may be excluding all data.
Fix: 1. Check the source data directly to confirm it contains data. 2. Review any filters applied in the data source settings. 3. For API sources, check pagination settings -- if the data path is wrong, pagination may stop after the first empty page.
File Upload Errors
"File format not supported"
When It Appears: Uploading a file as a data source
Cause: The file extension is not one of the supported types (.csv, .xlsx, .xls, .pdf).
Fix: 1. Verify your file has the correct extension. 2. If your file is a different format (e.g., .tsv, .json), convert it to CSV before uploading. 3. Renamed files may have the wrong extension -- check the actual file format.
"File exceeds maximum size"
When It Appears: Uploading a file
Cause: The file is larger than your plan's upload limit (Trial: 10 MB, Starter: 10 MB, Professional: 100 MB, Enterprise: 1 GB).
Fix: 1. Reduce the file size by removing unnecessary columns or rows. 2. Split the file into smaller segments. 3. Upgrade your plan for higher file size limits. See Plans and Pricing. 4. For very large datasets, connect directly to the source database instead of uploading files.
"No data found in file"
When It Appears: After uploading a CSV or Excel file
Cause: The file is empty, contains only headers with no data rows, or the sheet/tab selected during import has no content.
Fix: 1. Open the file in a spreadsheet application and verify it contains data. 2. For Excel files, check that you selected the correct sheet. 3. For CSV files, ensure the file is not using an unusual encoding that makes content invisible.
"Unable to parse PDF tables"
When It Appears: After uploading a PDF
Cause: The PDF contains images of tables rather than actual text-based table content, or the table layout is too complex for automatic extraction.
Fix: 1. Use a PDF with selectable text (not scanned images). 2. For scanned documents, run OCR (optical character recognition) software first. 3. Convert the PDF data to CSV or Excel format manually. 4. Simplify the table structure -- remove merged cells and multi-level headers.
OAuth and Integration Errors
"OAuth consent screen error"
When It Appears: During the OAuth authorization flow for Google Analytics, Google Sheets, Jira, etc.
Cause: The third-party service's consent screen could not load, or the user denied access.
Fix: 1. Ensure third-party cookies are enabled in your browser. 2. Disable ad blockers temporarily during the authorization flow. 3. Try a different browser (Chrome works most reliably). 4. If you clicked "Deny" accidentally, restart the connection process.
"Insufficient permissions on connected account"
When It Appears: After a successful OAuth connection, during the first sync
Cause: The account you authorized does not have enough permissions in the third-party service.
Fix: 1. For Google Analytics, ensure the account has at least Viewer access to the property. 2. For Jira, ensure the account has Browse Projects permission. 3. For Google Sheets, ensure you have at least Viewer access to the spreadsheet. 4. Re-authorize with a different account that has the required permissions.
Network and Infrastructure Errors
"DNS resolution failed"
See "Host not found" above.
"TLS handshake error"
When It Appears: Testing or syncing encrypted connections
Cause: The SSL/TLS configuration is incompatible between clariBI and the server. Often caused by outdated TLS versions (TLS 1.0 or 1.1) on the server.
Fix: 1. Ensure your server supports TLS 1.2 or higher. 2. Check that the server's certificate is valid and not expired. 3. If using a self-signed certificate, upload the CA certificate in the data source SSL settings.
"Proxy error" / "502 Bad Gateway"
When It Appears: During API source sync
Cause: An intermediary server between clariBI and the API returned an error. This is usually temporary.
Fix: 1. Wait a few minutes and retry the sync. 2. If persistent, check the API provider's status page for outages. 3. Contact support if the error continues for more than an hour.
Getting More Help
If your error is not listed here, or the suggested fix does not resolve the issue:
- Check the sync log -- go to the data source detail page and click View Logs for detailed error information.
- Contact support -- include the data source type, the exact error message, and the timestamp of the failure. Support can access server-side logs for deeper diagnosis.
- Check the status page -- for known outages or maintenance windows.