Elementary setup troubleshooting

Elementary has a handful of failure modes that show up consistently across installations. Most of them are silent — no error messages, just missing data or a report that looks right but shows nothing. This note covers each one with a diagnosis path and fix.

Empty report or no test results

The most common issue. You’ve installed the package, run dbt test, generated a report with edr report, and the test results section is empty.

Start by checking the table directly:

SELECT COUNT(*) FROM your_schema_elementary.elementary_test_results

If this returns zero after running dbt test, the package isn’t capturing results. On dbt 1.8+, this almost always means the materialization override macro is missing from your project. See Elementary dbt Materialization Override for the full explanation.

If you’re on an earlier version of dbt, check whether the on-run-end hooks are firing. You can confirm by looking at the dbt_run_results table instead:

SELECT COUNT(*) FROM your_schema_elementary.dbt_run_results

If dbt_run_results has data but elementary_test_results is empty, something is specifically blocking test result capture. The most common cause is conflicting materializations (see below).

The fix sequence after resolving the root cause:

dbt deps
dbt run --select elementary --full-refresh
dbt test

The --full-refresh recreates the Elementary tables cleanly.

”command not found: edr”

The Elementary CLI isn’t in your PATH. This happens when you install elementary-data in a virtual environment but run edr in a shell where that environment isn’t activated.

Two fixes:

Install in a virtual environment and activate it:

python3 -m venv venv_elementary
source venv_elementary/bin/activate
pip install 'elementary-data[bigquery]'
edr report

Or run through Python without PATH modification:

python -m edr report

The second option works regardless of which environment the package is installed in, as long as you’re running it from the right Python interpreter.

BigQuery location errors

Errors mentioning location, region, or multi-region when running edr report or edr monitor.

The Elementary CLI requires location explicitly in ~/.edr/profiles.yml. dbt infers location from the existing dataset, but Elementary does not. Add the parameter:

elementary:
  outputs:
    default:
      type: bigquery
      method: oauth
      project: your-project-id
      dataset: your_schema_elementary
      location: US  # or EU, or a specific region like europe-west1
      threads: 4

If you copied your dbt profile as a starting point, this is the field most likely to be missing.

Elementary tables created as views

Elementary tables appear in your warehouse as views rather than incremental tables. The report loads slowly or not at all, because views don’t hold data and every query recalculates from scratch.

Elementary configures its own tables as incremental materializations. If they’re showing up as views, a materialization config in your dbt_project.yml is overriding Elementary’s settings. Look for something like this:

models:
  your_project:
    +materialized: view  # This applies to everything, including Elementary

Or a schema-level override that catches the elementary schema:

models:
  your_project:
    +schema: view  # Accidentally catches elementary schema if configured that way

Fix the config to exclude the Elementary schema, then recreate the tables:

dbt run --select elementary --full-refresh

Databricks permission errors on shared clusters

Running edr against a Databricks shared cluster produces permission errors. The CLI tries to write to package directories during initialization, and shared cluster permissions block this.

Two options:

Switch to a single-user cluster for Elementary operations. Single-user clusters don’t have the same write restrictions.

Or add --update-dbt-package false to skip the package write:

edr report --update-dbt-package false
edr monitor --update-dbt-package false --slack-token $SLACK_TOKEN --slack-channel-name data-alerts

The --update-dbt-package false flag is safe to use in production. It just skips a step that re-downloads the Elementary dbt package before generating the report.

Checking that everything works

After resolving any issues, verify the full chain is working:

1. elementary_test_results has rows after dbt test
2. dbt_run_results has rows after dbt run
3. edr report generates an HTML file with test data visible
4. The report shows the expected number of tests and their pass/fail status

If step 3 produces a report but the data looks wrong (wrong date range, missing tests), check the flags you’re passing to edr report. --days-back 7 limits the report to the last 7 days; if your tests only ran once several weeks ago, increase this or omit the flag entirely.

For additional context on the profile configuration side of things, Elementary CLI profile configuration covers the full profile setup for each warehouse.