Overview
When a report fails to generate in clariBI, the system logs a specific error code and message. This guide lists every known error, explains what causes it, and provides step-by-step instructions to resolve it.
Reports in clariBI are AI-powered, meaning they use AI credits (2-5 per report depending on complexity) and rely on data sources to pull information. Failures can come from credit limits, data issues, or configuration problems.
Error: Insufficient AI Credits
Message: "Report generation requires X credits, but your organization has Y remaining."
Cause: Your organization does not have enough AI credits to generate this report.
Fix: 1. Check your credit balance at Settings > Billing > Usage. 2. If credits are exhausted, wait for the next billing cycle to reset them. 3. To get credits immediately, upgrade your plan. See Upgrading, Downgrading, and Cancelling Your Plan. 4. Consider generating a simpler report that costs fewer credits (a single-metric summary costs 2 credits vs. 5 for a comprehensive analysis).
See AI Credits: How They Work, What Counts, Checking Balance for details on credit costs.
Error: Data Source Connection Failed
Message: "Cannot connect to data source: [Source Name]. The connection is unavailable."
Cause: The data source used by the report is disconnected, paused, or experiencing an authentication error.
Fix: 1. Go to Data Sources in the sidebar. 2. Find the affected data source. It likely shows a red Error badge. 3. Click the data source to see the specific error: - Authentication expired: Click Re-authenticate and complete the OAuth flow or update credentials. - Connection refused: Check that the external database or API is online and accessible. - Paused: Click Resume to reactivate the data source. 4. After fixing the data source, retry the report generation.
Error: Query Timeout
Message: "Report generation timed out after 120 seconds."
Cause: The underlying data query took too long to complete. This typically happens with large datasets or complex queries.
Fix: 1. Narrow the date range. If the report spans years of data, try generating it for the last 90 days instead. 2. Reduce the scope. Use fewer data sources or focus on specific metrics. 3. Optimize the data source. If using a database, add indexes to frequently queried columns. If using BigQuery, ensure tables are partitioned. 4. Try again during off-peak hours. Shared data sources may be faster when fewer users are querying them. 5. Split into multiple reports. Instead of one comprehensive report, generate several focused reports.
Error: Template Not Found
Message: "The report template '[template_name]' could not be found."
Cause: The template was deleted, renamed, or is not available on your current plan.
Fix: 1. Go to Reports > Templates and verify the template exists. 2. If the template was deleted, choose a different template. 3. Some templates are only available on Professional and Enterprise plans. Check that your plan includes the template you need. 4. If you were using a custom template created by another team member, ask them to reshare it.
Error: Permission Denied
Message: "You do not have permission to generate reports."
Cause: Your organization role does not include report generation permissions.
Fix: 1. Check your role at Settings > Profile. Report generation requires the Analyst role or above. 2. Members and Viewers cannot generate reports. 3. Ask your organization's Owner or Administrator to upgrade your role.
See RBAC: Owner, Administrator, Analyst, Member, Viewer for permission details.
Error: Data Source Schema Changed
Message: "The data source schema has changed since this report template was configured."
Cause: A table or column that the report depends on was renamed, removed, or had its data type changed in the underlying data source.
Fix: 1. Go to Data Sources > [Source] > Schema. 2. Click Refresh Schema to pull the latest table and column definitions. 3. Edit the report template and update any field mappings that reference the changed columns. 4. If a table was deleted, you need to choose an alternative data source or table.
Error: Report Size Exceeded
Message: "The generated report exceeds the maximum size of 50MB."
Cause: The report is trying to include too much data, often from an unfiltered query that returns millions of rows.
Fix: 1. Add date range filters to limit the data. 2. Use aggregations (totals, averages) instead of raw row-level data. 3. Split the report into multiple smaller reports covering different segments. 4. Exclude large data visualizations or limit the number of charts.
Error: Scheduled Report Failed
Message: "Scheduled report '[Report Name]' failed to generate at the scheduled time."
Cause: Something went wrong during the automatic generation. The underlying cause is one of the errors above (usually data source connection or credit exhaustion).
Fix: 1. Check the report's Generation History for the specific error. 2. Fix the underlying issue (reconnect data source, add credits, etc.). 3. The report will automatically retry at the next scheduled time. 4. To generate immediately, click Run Now on the report page.
Error: Concurrent Report Limit
Message: "Maximum concurrent report generation limit reached. Please wait for current reports to complete."
Cause: Your organization is already generating the maximum number of reports simultaneously.
Fix: 1. Wait for current reports to finish. Check the Reports page for any reports showing "Generating" status. 2. Avoid queuing multiple large reports at the same time. 3. This limit exists to ensure fair resource allocation. Enterprise plans have higher concurrency limits.
Error: Invalid Parameters
Message: "Report parameters are invalid: [specific field]."
Cause: A required parameter is missing or has an invalid value (e.g., an end date before the start date).
Fix: 1. Review the report configuration. 2. Check date range parameters -- the start date must be before the end date. 3. Make sure all required fields are filled in. 4. If using the API, verify the JSON request body matches the expected schema. See Endpoint Reference.
Checking Report Generation History
Every report keeps a history of generation attempts:
- Go to Reports and click the report name.
- Click the History tab.
- Each entry shows:
- Status: Success, Failed, or Timeout
- Error message (if failed)
- Credits consumed (even failed attempts may use credits if the AI processing started)
- Duration
Preventing Future Failures
- Monitor data source health. Set up notifications for data source errors so you can fix them before they affect scheduled reports. See Data Source Sync Failures.
- Keep an eye on credit usage. If your team generates many reports, ensure you have enough credits to last the billing cycle.
- Test report templates. Before scheduling a report, generate it manually once to confirm it works.
- Use the API for automation. If you generate reports programmatically, implement error handling and retry logic. See the API endpoint reference.