Troubleshooting errors in Databox
Learn how to identify, understand, and resolve the different types of errors you may encounter while using Databox.
Databox displays different types of errors across the app to help you identify and troubleshoot problems as they occur. Use this guide to understand the different types of error messages you might encounter, how to interpret them, and where to go for more help.
Tip: You can also visit status.databox.com to check for any known issues that may be causing errors in your account.
Connections
Connection errors usually appear under the Status column in the Account Management > Data Manager > Connections section. These errors typically relate to:
- Expired or invalid authentication tokens
- Revoked access permissions from the API provider
- Changes to the connected account (e.g., password updates, deleted user)
Resolution
Most connection errors can be resolved by re-establishing the connection using the Reauthenticate button. If the error persists after reauthentication, we recommend checking the following:
- Permissions: Ensure you have the necessary permissions in the connected account to access the required data.
- Service status: The issue may be related to the API provider or database server. For status page links and more information, check the Technical Details and Handling Errors sections on the respective integration page in the Metric Library (search by integration name).
If the issue continues after these checks, contact our Support team via in-app chat or email at help@databox.com, and we’ll investigate further.
Data Sources
Data source errors appear under the Status column in the Data Manager > Data Sources page. These errors typically occur when:
- An issue occurred while adding the data source.
- The API provider is experiencing downtime or service interruptions.
- API limits or insufficient permissions are blocking data retrieval.
- The configuration of the source has changed (e.g., schema changes, renamed or removed fields).
Resolution
The steps to resolve data source errors will depend on the specific cause. Common actions include:
- Confirming permissions: Make sure you have the necessary access rights for the connected resource and its data.
- Reviewing settings: Use the Reconnect button, or click the down arrow (
) and select Reauthenticate to verify and re-establish the connection.
- Updating outdated metrics: If the data source structure has changed (e.g., fields removed or renamed), update any affected custom metrics accordingly.
- Waiting it out: If the issue is due to temporary factors like API rate limits or provider downtime, it may resolve itself automatically once the condition clears.
Additional information may also be available in the Handling Errors sections on the respective integration page in the Metric Library (search by integration name).
If the issue persists, contact our Support team via in-app chat or email at help@databox.com, and we’ll investigate further.
Datasets
Error messages for datasets and merged datasets appear under the Status column in Data Manager > Datasets and Data Manager > Merged Datasets. These errors are typically caused by:
- The dataset creation process being aborted before completion
- Issues during the initial or scheduled sync process
- Invalid join conditions in merged datasets
- Missing or mismatched fields between source datasets
- Errors in formulas or calculated columns (e.g., incorrect syntax, referencing nonexistent fields)
Resolution
To resolve dataset and merged dataset errors, consider the following steps:
- Retry the process: If the dataset creation was interrupted, try recreating it from scratch to ensure all steps are completed.
- Verify sync settings: Check the data sync history to identify any issues during the initial or scheduled sync. Click Refresh to re-run the sync if needed.
- Review join configurations: For merged datasets, double-check the selected join operator and conditions. Ensure that fields used in the join exist in both source datasets and are compatible.
- Check for field mismatches: Make sure all referenced fields exist and are named consistently across datasets.
- Validate formulas: If calculated columns are in use, confirm the formula syntax is correct and that all fields referenced in the formula are available and properly formatted.
Metric Builder
When building a custom metric, you may encounter an error if:
- The API provider returns an error based on the selected configuration
- One or more required fields (e.g., metric/measure, dimension, date) are missing
- Incompatible or invalid options are selected
Resolution
To resolve errors when creating a custom metric, try the following:
- Review required fields: Make sure all necessary selections (such as metric, dimension, date) are filled out.
- Check for compatibility issues: Some combinations of fields and filter may not be supported by the API provider. Try simplifying the configuration or adjusting your selections.
- Test incrementally: Build the metric step-by-step to isolate which setting is causing the issue.
If the issue persists, reach out to Support via in-app chat or email at help@databox.com with a screenshot and description of your configuration so we can help troubleshoot further.
Databoards and Datablocks
If one or more metrics fail to load in a Databoard or Datablock, an error tooltip may appear when you hover over the affected component. These messages can indicate:
- The selected metric(s) do not support the chosen date range and/or granularity
- API or sync-related issues are preventing data from being retrieved
- One or more Datablock settings are misconfigured or incomplete
Resolution
Start by identifying the scope of the issue — whether it originates from the connection, data source, dataset, metric, or the Datablock itself. If the root cause lies outside the Datablock, refer to the appropriate section above for troubleshooting steps.
If the error is isolated to the Datablock, try the following:
- Adjust the date range and/or granularity to values supported by the metric
- Review the Datablock configuration to ensure all required options (e.g., comparison settings, units) are properly set
- Re-add the metric to the Datablock to ensure it’s referencing the correct version or configuration
- Replace the Datablock if it appears broken or unresponsive after configuration updates
If the issue persists, contact Support via in-app chat or email at help@databox.com with a screenshot of the error tooltip and details of your setup so we can assist further.
Platform
Platform errors briefly appear as dismissible messages with a red background in the bottom-left corner the screen. These are usually caused by:
- Irregular or unexpected in-app behaviors
- Temporary browser, network or server issues
- Limitations or failures during execution of certain actions
Resolution
Some errors include a Report issue link that allows you to directly send error details to our team for investigation. If the link is available, click it to submit the report. You can also provide additional context to help us better identify and resolve the issue.
If the issue persists or the message doesn't include a reporting option, try refreshing the page, clearing your browser cache and cookies, or opening the app in an incognito/private browsing window. You can also reach out to our Support team via chat or email at help@databox.com with a screenshot and a brief description of what you were doing when the error appeared.
Still need help?
Visit our community, send us an email, or start a chat in Databox.