Troubleshooting
This section is aimed at collecting common issues users have to provide quick debug solutions.
I run `edr report` and get an empty report
I run `edr report` and get an empty report
If you get an empty report, there are several steps to understand what went wrong and try and fix it.
1. Validate elementary dbt package is deployed and working:
-
Check that dbt package version is the latest
-
Refer to the dbt package installation guide, and validate that your version in packages.yml is the one mentioned there. If not, upgrade and run
dbt deps. Make sure to executedbt run --select elementaryfor the package tables to be created. -
Check if the table
elementary_test_resultsexists and has data -
If the table does not exist - refer to the dbt package installation guide. Make sure to execute
dbt run --select elementaryfor the package tables to be created. -
If the table exists but has no data - Did you execute
dbt testsince deploying the package and creating the models? -
If yes, make sure the table was created as an incremental table (not a regular table or view).
-
If not, there is a materialization configuration in your
dbt_project.ymlfile that overrides the package config. Remove it, and rundbt run --select elementary --full-refreshto recreate the tables. After that rundbt testagain and check if there is data. -
Still no data in the table? Reach out to the elementary team at #support on Slack.
2. Validate that the CLI was properly installed
-
Check the CLI version is the latest
-
Use the command
pip show elementary-datato detect your version, and validate that it is the latest one. If not, runpip install elementary-data --upgrade. -
Try to force update the CLI internal packages
-
Run the CLI with the flag for force updating the packages:
edr report -u true
3. Validate that the CLI has a working connection profile in the right path and format
- Default path:
HOME_DIR/.dbt/profiles.yml. If saved elsewhere, make sure to run dbt run and dbt test with—profiles-dir <profiles.yml path> - Profile name:
elementary - Make sure that the elementary profile is a top-level profile, with the same indentation of the profiles you have already set up
- Schema name: The schema of the elementary models. The default name is
<your_dbt_project_schema>_elementary
4. Validate the schema configuration for elementary models in your dbt_project.yml
5. Still not working? Collect the following logs and reach our to the elementary team at #community-support on Slack
- edr.log - Created on the execution folder of the CLI.
- dbt.log - Created under the package location at
/site-packages/monitor/dbt_project/logs/dbt.logYou can find the full path of the package location usingpip show elementary-data.
Error: `cannot insert into a view`
Error: `cannot insert into a view`
Elementary dbt package includes macros that run insert commands to some of the models.
This error means that these models were materialized as views, and not as tables.
The reason for the error is probably a configuration on your dbt_project.yml file, under the key materialization.
We recommend moving this config to be strictly for models in your package, or else it will override the materialization of packages:
Error: `command not found: edr` on macOS
Error: `command not found: edr` on macOS
In Python on macOS, when you globally install a package that has executables, such as Elementary’s edr, it places the executable in a location that is not under the default PATH which is the environment variable that is used for executable lookups. Here’s an example of the warning you might receive upon running python3 -m pip install elementary-data.
As you can see, edr is not found by default upon installation.
There are multiple ways to solve this.
- Use the absolute path.
- Edit your shell’s configuration file(
~/.zshrc) and append Python’s library path.
- Use Python’s virtual environment.
Error: `command not found: edr` on Windows
Error: `command not found: edr` on Windows
If you got a message Successfully installed elementary-data but get a command not found error, it is probably because of a missing path in your environment variables.
Look for a warning in your terminal saying:
Warning: the script edr.exe is installed in '<path>' which is not on PATH
This is the path that needs to be added to your windows env vars, run:
After that restart your CMD and try edr again.
Error: No such command 'monitor'
Error: No such command 'monitor'
This means the installation was not completed successfully. This is usually a Python dependencies issue.
Please try installing again on a clean virtual env:
WARNING - Installed package 'elementary' is overriding the built-in materialization 'XXX'
WARNING - Installed package 'elementary' is overriding the built-in materialization 'XXX'
Starting from dbt 1.8 and above, 3rd party dbt packages cannot override dbt materializations without an explicit configuration from users. Elementary utilizes this dbt mechanism to add reporting functionality to non-Elementary tests (such as native dbt tests and expectations):
- Collection of the total number of failed rows.
- Collection of failed row samples.
The warning above may appear in one of the following two cases:
- If you are using the most recent version of dbt 1.6 or 1.7 - this warning will appear by default, since it indicates the aforementioned behavior change in dbt 1.8.
- If you are using dbt 1.8 and above, this warning will NOT appear by default, however it will start appearing once you set the flag
require_explicit_package_overrides_for_builtin_materializationstofalseas required in the dbt package installation guide.
In either case, please ignore it for now. This is a temporary measure and we are working with the dbt team on a longer term solution.
I changed the training period but the results are the same
I changed the training period but the results are the same
Elementary tests have a var named training_period.
If you change it after executing elementary tests, you will need to run a full refresh to the metrics collected. This will make the next tests collect data for the new training_period timeframe.
The steps are:
- Change var
training_periodin yourdbt_project.yml. - Full refresh of the model ‘data_monitoring_metrics’ by running
dbt run --select data_monitoring_metrics --full-refresh. - Running the elementary tests again.
If you want the Elementary UI to show data for a longer period of time, use the days-back option of the CLI:
edr report --days-back 45
Error when trying to run parallel dbt jobs
Error when trying to run parallel dbt jobs
When writing to the dbt_artifacts tables in the Elementary schema, data is deleted and reinserted. Running parallel jobs through an orchestrator can lead to errors, as multiple jobs may attempt to modify the same tables simultaneously.
To prevent this, you should:
For scheduled updates to dbt_artifacts (e.g., a daily job), run:
Elementary on-run-end hooks are taking a long time
Elementary on-run-end hooks are taking a long time
The dbt_columns table in the Elementary schema can take a while to update, especially for large projects. This table is only used by Elementary Cloud, so if you’re not relying on it (or want to speed up your runs), you can disable it safely without affecting any other functionality.
To skip updating this table, add the following to your dbt_project.yml:
My problem is not listed here
My problem is not listed here
If you’re experiencing issues of any kind, reach out on the #community-support channel. Elementary AI and the team will be happy to help.
Other issues?
Ask us on Slack, we are very responsive!
Troubleshooting
This section is aimed at collecting common issues users have to provide quick debug solutions.
I run `edr report` and get an empty report
I run `edr report` and get an empty report
If you get an empty report, there are several steps to understand what went wrong and try and fix it.
1. Validate elementary dbt package is deployed and working:
-
Check that dbt package version is the latest
-
Refer to the dbt package installation guide, and validate that your version in packages.yml is the one mentioned there. If not, upgrade and run
dbt deps. Make sure to executedbt run --select elementaryfor the package tables to be created. -
Check if the table
elementary_test_resultsexists and has data -
If the table does not exist - refer to the dbt package installation guide. Make sure to execute
dbt run --select elementaryfor the package tables to be created. -
If the table exists but has no data - Did you execute
dbt testsince deploying the package and creating the models? -
If yes, make sure the table was created as an incremental table (not a regular table or view).
-
If not, there is a materialization configuration in your
dbt_project.ymlfile that overrides the package config. Remove it, and rundbt run --select elementary --full-refreshto recreate the tables. After that rundbt testagain and check if there is data. -
Still no data in the table? Reach out to the elementary team at #support on Slack.
2. Validate that the CLI was properly installed
-
Check the CLI version is the latest
-
Use the command
pip show elementary-datato detect your version, and validate that it is the latest one. If not, runpip install elementary-data --upgrade. -
Try to force update the CLI internal packages
-
Run the CLI with the flag for force updating the packages:
edr report -u true
3. Validate that the CLI has a working connection profile in the right path and format
- Default path:
HOME_DIR/.dbt/profiles.yml. If saved elsewhere, make sure to run dbt run and dbt test with—profiles-dir <profiles.yml path> - Profile name:
elementary - Make sure that the elementary profile is a top-level profile, with the same indentation of the profiles you have already set up
- Schema name: The schema of the elementary models. The default name is
<your_dbt_project_schema>_elementary
4. Validate the schema configuration for elementary models in your dbt_project.yml
5. Still not working? Collect the following logs and reach our to the elementary team at #community-support on Slack
- edr.log - Created on the execution folder of the CLI.
- dbt.log - Created under the package location at
/site-packages/monitor/dbt_project/logs/dbt.logYou can find the full path of the package location usingpip show elementary-data.
Error: `cannot insert into a view`
Error: `cannot insert into a view`
Elementary dbt package includes macros that run insert commands to some of the models.
This error means that these models were materialized as views, and not as tables.
The reason for the error is probably a configuration on your dbt_project.yml file, under the key materialization.
We recommend moving this config to be strictly for models in your package, or else it will override the materialization of packages:
Error: `command not found: edr` on macOS
Error: `command not found: edr` on macOS
In Python on macOS, when you globally install a package that has executables, such as Elementary’s edr, it places the executable in a location that is not under the default PATH which is the environment variable that is used for executable lookups. Here’s an example of the warning you might receive upon running python3 -m pip install elementary-data.
As you can see, edr is not found by default upon installation.
There are multiple ways to solve this.
- Use the absolute path.
- Edit your shell’s configuration file(
~/.zshrc) and append Python’s library path.
- Use Python’s virtual environment.
Error: `command not found: edr` on Windows
Error: `command not found: edr` on Windows
If you got a message Successfully installed elementary-data but get a command not found error, it is probably because of a missing path in your environment variables.
Look for a warning in your terminal saying:
Warning: the script edr.exe is installed in '<path>' which is not on PATH
This is the path that needs to be added to your windows env vars, run:
After that restart your CMD and try edr again.
Error: No such command 'monitor'
Error: No such command 'monitor'
This means the installation was not completed successfully. This is usually a Python dependencies issue.
Please try installing again on a clean virtual env:
WARNING - Installed package 'elementary' is overriding the built-in materialization 'XXX'
WARNING - Installed package 'elementary' is overriding the built-in materialization 'XXX'
Starting from dbt 1.8 and above, 3rd party dbt packages cannot override dbt materializations without an explicit configuration from users. Elementary utilizes this dbt mechanism to add reporting functionality to non-Elementary tests (such as native dbt tests and expectations):
- Collection of the total number of failed rows.
- Collection of failed row samples.
The warning above may appear in one of the following two cases:
- If you are using the most recent version of dbt 1.6 or 1.7 - this warning will appear by default, since it indicates the aforementioned behavior change in dbt 1.8.
- If you are using dbt 1.8 and above, this warning will NOT appear by default, however it will start appearing once you set the flag
require_explicit_package_overrides_for_builtin_materializationstofalseas required in the dbt package installation guide.
In either case, please ignore it for now. This is a temporary measure and we are working with the dbt team on a longer term solution.
I changed the training period but the results are the same
I changed the training period but the results are the same
Elementary tests have a var named training_period.
If you change it after executing elementary tests, you will need to run a full refresh to the metrics collected. This will make the next tests collect data for the new training_period timeframe.
The steps are:
- Change var
training_periodin yourdbt_project.yml. - Full refresh of the model ‘data_monitoring_metrics’ by running
dbt run --select data_monitoring_metrics --full-refresh. - Running the elementary tests again.
If you want the Elementary UI to show data for a longer period of time, use the days-back option of the CLI:
edr report --days-back 45
Error when trying to run parallel dbt jobs
Error when trying to run parallel dbt jobs
When writing to the dbt_artifacts tables in the Elementary schema, data is deleted and reinserted. Running parallel jobs through an orchestrator can lead to errors, as multiple jobs may attempt to modify the same tables simultaneously.
To prevent this, you should:
For scheduled updates to dbt_artifacts (e.g., a daily job), run:
Elementary on-run-end hooks are taking a long time
Elementary on-run-end hooks are taking a long time
The dbt_columns table in the Elementary schema can take a while to update, especially for large projects. This table is only used by Elementary Cloud, so if you’re not relying on it (or want to speed up your runs), you can disable it safely without affecting any other functionality.
To skip updating this table, add the following to your dbt_project.yml:
My problem is not listed here
My problem is not listed here
If you’re experiencing issues of any kind, reach out on the #community-support channel. Elementary AI and the team will be happy to help.
Other issues?
Ask us on Slack, we are very responsive!