Introduction

Diesel uses a migration system where each migration is a directory with up.sql and down.sql files. When diesel migration run fails with "no migrations found" or "migration directory not found", the database schema cannot be updated. This commonly happens after cloning a repository without diesel CLI installed, when migration directories are misnamed, or when diesel.toml points to the wrong path.

Symptoms

  • diesel migration run outputs "No migrations found"
  • diesel setup fails with "Could not find migrations directory"
  • Database tables not created after running migrations
  • Migration files exist but diesel does not see them
  • diesel migration list shows empty list despite migration files

Error output: `` $ diesel migration run Looking for migrations in /home/user/project/migrations Could not find any migrations in /home/user/project/migrations

Common Causes

  • diesel.toml missing or migrations_directory path wrong
  • Migration directory name does not follow VERSION_NAME format
  • Migrations directory not at project root level
  • diesel CLI not installed or wrong version
  • PostgreSQL/MySQL/SQLite URL not configured in .env

Step-by-Step Fix

  1. 1.Verify diesel.toml configuration:
  2. 2.```toml
  3. 3.# diesel.toml - must be at project root
  4. 4.[print_schema]
  5. 5.file = "src/schema.rs"

[migrations_directory] dir = "migrations" ```

If missing, regenerate: ```bash # In project root diesel print-config # Should show: # migrations_directory = /path/to/project/migrations

# If wrong, fix diesel.toml manually ```

  1. 1.Create migration with correct naming format:
  2. 2.```bash
  3. 3.# Correct format: diesel migration <name>
  4. 4.# Creates: migrations/TIMESTAMP_create_users/
  5. 5.diesel migration generate create_users

# Verify structure ls -la migrations/ # migrations/ # 2026-04-09-100000_create_users/ # up.sql # down.sql

# WRONG names that diesel will not find: # migrations/create_users/ (no timestamp) # migrations/20260409_create_users/ (wrong timestamp format) ```

  1. 1.Write proper up.sql and down.sql:
  2. 2.```sql
  3. 3.-- migrations/20260409100000_create_users/up.sql
  4. 4.CREATE TABLE users (
  5. 5.id SERIAL PRIMARY KEY,
  6. 6.email VARCHAR NOT NULL UNIQUE,
  7. 7.name VARCHAR NOT NULL,
  8. 8.created_at TIMESTAMP NOT NULL DEFAULT NOW(),
  9. 9.updated_at TIMESTAMP NOT NULL DEFAULT NOW()
  10. 10.);

CREATE INDEX idx_users_email ON users(email);

-- migrations/20260409100000_create_users/down.sql DROP TABLE users; ```

  1. 1.Configure database URL and run migrations:
  2. 2.```bash
  3. 3.# Set database URL
  4. 4.export DATABASE_URL="postgresql://user:pass@localhost/mydb"

# Or use .env file echo "DATABASE_URL=postgresql://user:pass@localhost/mydb" > .env

# Run setup (creates database + __diesel_schema_migrations table) diesel setup

# Run all pending migrations diesel migration run

# Verify diesel migration list # Migrations: # 2026-04-09-100000_create_users [run] ```

  1. 1.Redo a migration that failed mid-execution:
  2. 2.```bash
  3. 3.# Check migration status
  4. 4.diesel migration list

# If a migration partially ran, redo it diesel migration redo

# Or redo specific number diesel migration redo -n 3 # Redo last 3 migrations

# If redo fails, manually fix __diesel_schema_migrations # Connect to database and check: psql -d mydb -c "SELECT * FROM __diesel_schema_migrations ORDER BY version DESC;"

# Remove stuck migration entry if needed psql -d mydb -c "DELETE FROM __diesel_schema_migrations WHERE version = '20260409100000';"

# Then re-run diesel migration run ```

  1. 1.Debug diesel CLI issues:
  2. 2.```bash
  3. 3.# Check diesel CLI version
  4. 4.diesel --version
  5. 5.# Should be 2.1.0+ for Diesel 2.x

# Check config diesel print-config

# Verify database connection diesel database setup

# Run with verbose output RUST_LOG=diesel=debug diesel migration run ```

Prevention

  • Always use diesel migration generate <name> instead of manual directory creation
  • Commit diesel.toml and migration directories to version control
  • Add DATABASE_URL to .env and .env.example
  • Run diesel migration run in CI pipeline before tests
  • Never edit migration files after they have been run in production
  • Use diesel migration redo in development, never in production