> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lightdash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to dbt 1.10: Fix Meta and Tags Configuration Warnings

> Learn how to fix dbt 1.10 deprecation warnings for `meta` and `tags` properties, and migrate your project automatically with MetaMove.

When you upgrade to dbt 1.10, you'll likely encounter deprecation warnings that look like this:

```
Warning: while parsing model config: Ignore unexpected key "meta"
Warning: while parsing model config: Ignore unexpected key "tags"
```

These warnings indicate that dbt is changing how `meta` and `tags` should be structured in your YAML files. Instead of manually updating potentially hundreds of files, you can use MetaMove - a CLI tool specifically designed to automate this migration.

## What Changed in dbt 1.10?

Starting in dbt 1.10, you will receive deprecation warnings for dbt code that will become invalid in the future, including custom inputs like unrecognized resource properties and configurations. Some properties are moving to configs, including `meta` and `tags`.

The key change affects how you define `meta` and `tags` properties across your dbt project:

**Before (dbt \< 1.10):**

```yaml theme={null}
models:
  - name: my_model
    meta:
      owner: "Data Team"
      priority: "high"
    tags: ["core", "customer"]
    columns:
      - name: id
        meta:
          is_primary_key: true
        tags: ["identifier"]
```

**After (dbt 1.10+):**

```yaml theme={null}
models:
  - name: my_model
    config:
      meta:
        owner: "Data Team"
        priority: "high"
      tags: ["core", "customer"]
    columns:
      - name: id
        config:
          meta:
            is_primary_key: true
          tags: ["identifier"]
```

## Why This Change Matters

Previously, dbt allowed you to configure inputs largely unconstrained. Without a set of strictly defined inputs, it becomes challenging to validate your project's configuration, creating unintended issues such as silently ignoring misspelled properties and configurations.

This change provides several benefits:

* **Better Validation**: dbt can now catch misspelled properties and configurations
* **Consistent Structure**: All custom attributes must be nested under the `meta` config
* **Future-Proofing**: Prevents conflicts when dbt introduces new reserved properties

## Automated Migration with MetaMove

Rather than manually updating your YAML files, use MetaMove - a CLI tool built specifically for this migration. MetaMove automatically transforms your files while preserving comments and formatting.

### Installation

Install MetaMove using pipx (recommended):

```bash theme={null}
pip install pipx  # if you don't have it
pipx install metamove
```

### Basic Usage

Transform a single YAML file:

```bash theme={null}
metamove models/my_model.yml
```

Transform multiple files:

```bash theme={null}
metamove models/* seeds/* snapshots/*
```

Transform all YAML files in your dbt project:

```bash theme={null}
metamove models/**/* seeds/**/* snapshots/**/*
```

### Safe Migration Process

MetaMove follows a safe-by-default approach:

1. **Test First**: By default, transformed files are saved to a `transformed` directory:
   ```bash theme={null}
   metamove models/*  # saves to ./transformed/
   ```

2. **Review Changes**: Compare the original and transformed files to ensure accuracy.

3. **Apply In-Place**: Once confident, transform files in place:
   ```bash theme={null}
   metamove models/* -i
   ```

### Advanced Options

Specify a custom output directory:

```bash theme={null}
metamove models/* -o my_transformed_models
```

The tool automatically processes only `.yml` and `.yaml` files, so wildcards work safely:

```bash theme={null}
# Transform specific model directories
metamove models/marts/* models/staging/*

# Transform all nested directories
metamove models/**/*
```

## What MetaMove Handles

MetaMove intelligently processes:

* **Nested Structures**: `meta` and `tags` at any nesting level, including inside `columns`
* **Existing Config Blocks**: Merges new values into existing `config` sections
* **All YAML Types**: Dictionaries, lists, and scalar values
* **Formatting Preservation**: Maintains your comments and whitespace
* **Complex Cases**: Handles edge cases following dbt precedence rules

## Manual Migration (If Needed)

If you prefer to migrate manually or need to understand the changes, here are the key transformations:

### Model-Level Changes

**Before:**

```yaml theme={null}
models:
  - name: customer_metrics
    description: "Customer analytics model"
    meta:
      owner: "analytics_team"
      sla: "daily"
    tags: ["core", "customer", "metrics"]
```

**After:**

```yaml theme={null}
models:
  - name: customer_metrics
    description: "Customer analytics model"
    config:
      meta:
        owner: "analytics_team"
        sla: "daily"
      tags: ["core", "customer", "metrics"]
```

### Column-Level Changes

**Before:**

```yaml theme={null}
models:
  - name: customers
    columns:
      - name: customer_id
        description: "Unique customer identifier"
        meta:
          is_primary_key: true
          data_type: "uuid"
        tags: ["pii", "identifier"]
```

**After:**

```yaml theme={null}
models:
  - name: customers
    columns:
      - name: customer_id
        description: "Unique customer identifier"
        config:
          meta:
            is_primary_key: true
            data_type: "uuid"
          tags: ["pii", "identifier"]
```

### Source-Level Changes

**Before:**

```yaml theme={null}
sources:
  - name: raw_data
    schema: staging
    meta:
      loader: "fivetran"
      freshness_sla: "1 hour"
    tags: ["external", "raw"]
    tables:
      - name: users
        meta:
          row_count: 50000
        tags: ["pii"]
```

**After:**

```yaml theme={null}
sources:
  - name: raw_data
    schema: staging
    config:
      meta:
        loader: "fivetran"
        freshness_sla: "1 hour"
      tags: ["external", "raw"]
    tables:
      - name: users
        config:
          meta:
            row_count: 50000
          tags: ["pii"]
```

## Other dbt 1.10 Changes to Consider

While migrating `meta` and `tags`, be aware of other properties moving to configs:

* `freshness` (for sources)
* `docs`
* `group`
* `access`

These properties should now be set under the `config` block following the same pattern as `meta` and `tags`.

## Handling Warnings During Migration

If you're using `--warn-error` flags that promote warnings to errors, you may need to adjust your configuration during migration:

```yaml theme={null}
# In dbt_project.yml
flags:
  warn_error_options:
    warn: ["Deprecations"]  # Keep deprecation warnings as warnings
    error: ["other_warning_types"]  # Promote other warnings to errors
```

This allows you to continue working while addressing deprecation warnings gradually.

## Testing Your Migration

After migrating your files:

1. **Run dbt parse**: Ensure your project parses without errors:
   ```bash theme={null}
   dbt parse
   ```

2. **Check for Warnings**: Run a simple command to verify warnings are resolved:
   ```bash theme={null}
   dbt compile --select my_model
   ```

3. **Run Tests**: Execute your test suite to ensure functionality is preserved:
   ```bash theme={null}
   dbt test
   ```

## Best Practices

* **Backup First**: Always backup your project before running any migration tool
* **Test in Development**: Run the migration in a development branch first
* **Review Changes**: Use git diff to review all changes before committing
* **Migrate Incrementally**: For large projects, consider migrating one directory at a time
* **Update CI/CD**: Ensure your deployment processes work with the new structure

## Troubleshooting Common Issues

### "Config block already exists" Errors

If you have existing `config` blocks, MetaMove will merge the new properties. However, if you encounter conflicts:

1. Review the specific file causing issues
2. Manually resolve conflicts between existing and new config properties
3. Re-run MetaMove on the corrected file

### Unexpected YAML Structure

If your YAML files have unusual structures that MetaMove doesn't handle:

1. Note the problematic files in the tool output
2. Manually migrate these files using the patterns shown above
3. Use MetaMove for the remaining standard files

### Performance with Large Projects

For projects with hundreds of YAML files:

1. Run MetaMove on subdirectories rather than the entire project at once
2. Use the `-o` flag to organize transformed files by directory
3. Process files in batches to make review manageable

## Conclusion

Migrating to dbt 1.10's new `meta` and `tags` structure is essential for maintaining a robust, future-proof dbt project. MetaMove makes this migration straightforward by automating the tedious work while preserving your careful formatting and comments.

The goal is to enable you to work with more safety, feedback, and confidence going forward. By moving `meta` and `tags` under `config` blocks, dbt can provide better validation and prevent the subtle issues that arise from misspelled properties or unintended conflicts.

Start your migration today:

```bash theme={null}
pipx install metamove
metamove models/* --help
```

For more information about dbt 1.10 changes and package management best practices, check out the [official dbt upgrade guide](https://docs.getdbt.com/docs/dbt-versions/core-upgrade/upgrading-to-v1.10) and explore [MetaMove on GitHub](https://github.com/lightdash/metamove) for advanced usage and contributing opportunities.