What causes "Failed to create embedded migrations instance" in diesel-rs/diesel?

Verify the path argument points at the migrations root directory that exists relative to the crate (e.g. `embed_migrations!("migrations")`) and that the folder is present at compile time

diesel-rs/diesel · error

Failed to create embedded migrations instance

Error message

Failed to create embedded migrations instance

What it means

This panic occurs inside the `embed_migrations!` proc macro, which embeds a migrations directory into the binary at compile time. The macro generates Rust tokens for an embedded migrations instance and then parses that token string back into a TokenStream; the `.expect` fires when the generated code fails to re-parse, which means macro expansion produced invalid Rust — nearly always because the migrations directory is missing, empty/malformed, or the supplied path is wrong. It is a compile-time panic, so the build fails rather than producing a runtime error.

Solutions

Verify the path argument points at the migrations root directory that exists relative to the crate (e.g. `embed_migrations!("migrations")`) and that the folder is present at compile time
Check each migration subfolder follows the `<version>_<name>` convention and contains valid `up.sql`/`down.sql` files
Ensure the migrations directory is committed and copied into build contexts (git, Dockerfile COPY, CI checkout)
Run `cargo clean` and rebuild to rule out stale macro expansion artifacts
If using diesel_cli, regenerate a known-good migrations layout with `diesel setup` / `diesel migration generate <name>`

Example fix

// before (path missing at compile time)
embed_migrations!("./migrations");
// after (correct path relative to crate root, directory committed)
embed_migrations!("migrations");

Defensive patterns

Strategy: validation

Validate before calling

// before compiling, assert the migrations dir exists and is non-empty (build.rs or shell)
use std::fs;
let dir = std::path::Path::new("migrations");
assert!(dir.is_dir(), "migrations directory not found at ./migrations");
let has_migrations = fs::read_dir(dir)
    .unwrap()
    .filter_map(|e| e.ok())
    .any(|e| e.path().is_dir());
assert!(has_migrations, "no migration folders inside ./migrations");

Prevention

Keep migrations at the conventional `./migrations` path relative to the crate using `embed_migrations!`
Commit the migrations directory and ensure Docker/CI images COPY it before `cargo build`
Name migration folders strictly as `<version>_<description>` with `up.sql`/`down.sql` inside
Create migrations only via `diesel migration generate` to guarantee a valid layout
After moving code between crates, re-check the macro's path argument (it is relative to CARGO_MANIFEST_DIR)

When it happens

Trigger: Calling `embed_migrations!("path/to/migrations")` (or `embed_migrations!()` with the default `migrations` dir) where the directory does not exist, contains migration folders that violate the `<version>_<name>` naming/layout rules, or where the path argument is not a valid string literal; also triggered by corrupted or empty migrations directories picked up during macro expansion.

Common situations: Wrong working directory or path passed to the macro in Cargo.toml-based builds; migrations folder not committed to the repo or excluded by CI checkout; renamed/deleted migrations directory after a refactor; accidentally pointing the macro at `migrations/xxx/up.sql` instead of the migrations root; Docker builds where the migrations dir is not COPY'd into the image.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of diesel-rs/diesel@6fa6ed01b2 (2026-09-07). Data as JSON: /api/errors/c5adf6bf48b13806. Report an issue: GitHub.

Appendix: source

Thrown at diesel_migrations/migrations_macros/src/lib.rs:127

/// external file changes/is added. This implies that `embed_migrations!`
/// cannot regenerate the list of embedded migrations if **only** the
/// migrations are changed. This limitation can be solved by adding a
/// custom `build.rs` file to your crate, such that the crate is rebuild
/// if the migration directory changes.
///
/// Add the following `build.rs` file to your project to fix the problem
///
/// ```
/// fn main() {
///     println!("cargo:rerun-if-changed=path/to/your/migration/dir/relative/to/your/Cargo.toml");
/// }
/// ```
#[proc_macro]
pub fn embed_migrations(input: TokenStream) -> TokenStream {
    embed_migrations::expand(input.to_string())
        .to_string()
        .parse()
        .expect("Failed to create embedded migrations instance")
}

View on GitHub (pinned to 6fa6ed01b2)