# dbt docs generate: 'NoneType' object is not iterable

## TL;DR

`dbt docs generate` builds `catalog.json` by asking your warehouse for table and column metadata through the adapter, then iterating over the results. `'NoneType' object is not iterable` means the adapter returned NULL (None) where dbt expected a value, usually a column attribute such as the column position, or a missing schema name, and dbt crashed iterating it. Re-run with `--debug` to get the traceback, find which relation returns the NULL metadata (common culprits: BigQuery external tables, Oracle null column IDs, custom adapters), and either upgrade the adapter, exclude the relation, or fix the adapter's catalog query.

```text
TypeError: 'NoneType' object is not iterable
# during: dbt docs generate / Building catalog
```

## Steps

### 1. Reproduce with a full traceback

```bash
dbt docs generate --debug 2>&1 | tail -60
```

Expected: a Python traceback ending in `TypeError: 'NoneType' object is not iterable`, with frames in `dbt/task/generate.py` (the catalog builder) or your adapter's `impl.py` / `catalog.sql`. Note the frame above the TypeError: it usually names the relation or the metadata field being processed.

### 2. Identify the relation with NULL metadata

The classic triggers are all the same family:

- **BigQuery external tables**: the adapter can return a null column index for external tables (dbt-bigquery#1079). If your project selects from external tables, this is suspect number one.
- **Oracle**: null values in `column_id` crash the catalog builder when it converts the index (dbt-oracle#86, fixed in dbt-oracle 1.6.0).
- **Databases or adapters without schema reporting**: a null `table_schema` breaks the catalog filter step.
- **Custom or community adapters**: the adapter's `catalog.sql` macro returns nulls for fields dbt-core expects populated.

Narrow it down by generating docs for a subset:

```bash
dbt docs generate --select [suspect_model_or_source]
```

Expected: the command succeeds when the offending relation is excluded, confirming which one carries the NULL metadata.

### 3. Apply the fix for your trigger

- **Upgrade the adapter** if a fixed version exists (for example dbt-oracle 1.6.0 or later, or a dbt-bigquery version past the 1.7.3 external-table regression). Then re-run `dbt docs generate`.
- **BigQuery external tables**: if you cannot upgrade, exclude the external-table-backed nodes from docs generation with `--select` / `--exclude`, or make sure the external table exposes queryable column metadata.
- **Custom adapter**: patch the adapter's catalog query to coalesce nulls, for example `coalesce(column_id, 0) as ordinal_position`, so dbt never iterates None.
- **Null-schema databases**: set an explicit schema on the offending source or model so the catalog query returns a real schema name.

Expected: `dbt docs generate` completes with `Catalog written to target/catalog.json`.

### 4. Verify the catalog

```bash
ls -la target/catalog.json && python3 -c "import json; d=json.load(open('target/catalog.json')); print(len(d.get('nodes', {})), 'nodes cataloged')"
```

Expected: `catalog.json` exists and reports your node count. Then run `dbt docs serve`, open the printed address in a browser, and confirm the previously crashing nodes render.

## When to use this skill

- `dbt docs generate` crashes during the "Building catalog" phase with `TypeError: 'NoneType' object is not iterable`, or its siblings `'NoneType' object has no attribute 'lower'` and `int() argument ... not 'NoneType'`. Same family, same diagnostic path.

## When NOT to use this skill

- The NoneType error happens during `dbt run`, `dbt compile`, or `dbt test` instead of docs generate. That is a Jinja or model-code issue, usually a macro returning None where a list was expected. Different fix.
- `dbt docs generate` fails with a database connection or permission error. That is credentials or networking, not metadata.

## Variant phrasings

### dbt docs generate TypeError NoneType

Any `TypeError` mentioning `NoneType` during catalog building belongs to this family.

### Encountered an error while generating catalog

dbt logs `Encountered an error while generating catalog: 'NoneType' ...` as a warning before the hard failure. Same root cause.

## Why it happens

`dbt docs generate` does two things: it renders the manifest, then it builds the data catalog by querying your warehouse's information schema through adapter-specific SQL. dbt-core then iterates the returned rows to assemble `catalog.json`. Warehouse metadata is not always complete: external tables, exotic adapters, and some system views return NULL for fields like column position or schema name. dbt-core historically assumed those fields are populated, so a single NULL row crashes the whole catalog build with a NoneType TypeError. Fixes land in the adapters (coalescing the nulls), which is why upgrading the adapter is often the entire fix.

## Edge cases

- The crash is intermittent: a recently added source or external table is the usual change. Check recent additions to `models/` and your `sources.yml` files.
- `--debug` shows the failure inside adapter or `agate` code rather than `generate.py`: still the same family. The null came from the warehouse through the adapter.
- You only need docs for part of the project: `dbt docs generate --select [subset]` permanently sidesteps relations you do not need cataloged.


## Matched thread
Source: Vectle search thread
Original query: ""dbt docs generate: 'NoneType' object is not iterable""
Key terms: docs, generate, iterable, nonetype, object