{"record":{"id":"c5adf6bf48b13806","repo":"diesel-rs/diesel","slug":"failed-to-create-embedded-migrations-instance","errorCode":null,"errorMessage":"Failed to create embedded migrations instance","messagePattern":"Failed to create embedded migrations instance","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"diesel_migrations/migrations_macros/src/lib.rs","lineNumber":127,"sourceCode":"/// external file changes/is added. This implies that `embed_migrations!`\n/// cannot regenerate the list of embedded migrations if **only** the\n/// migrations are changed. This limitation can be solved by adding a\n/// custom `build.rs` file to your crate, such that the crate is rebuild\n/// if the migration directory changes.\n///\n/// Add the following `build.rs` file to your project to fix the problem\n///\n/// ```\n/// fn main() {\n///     println!(\"cargo:rerun-if-changed=path/to/your/migration/dir/relative/to/your/Cargo.toml\");\n/// }\n/// ```\n#[proc_macro]\npub fn embed_migrations(input: TokenStream) -> TokenStream {\n    embed_migrations::expand(input.to_string())\n        .to_string()\n        .parse()\n        .expect(\"Failed to create embedded migrations instance\")\n}\n","sourceCodeStart":109,"sourceCodeEnd":129,"githubUrl":"https://github.com/diesel-rs/diesel/blob/6fa6ed01b24b24248ab2a611698d0a7c6a2e9120/diesel_migrations/migrations_macros/src/lib.rs#L109-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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>`"],"exampleFix":"// before (path missing at compile time)\nembed_migrations!(\"./migrations\");\n// after (correct path relative to crate root, directory committed)\nembed_migrations!(\"migrations\");","handlingStrategy":"validation","validationCode":"// before compiling, assert the migrations dir exists and is non-empty (build.rs or shell)\nuse std::fs;\nlet dir = std::path::Path::new(\"migrations\");\nassert!(dir.is_dir(), \"migrations directory not found at ./migrations\");\nlet has_migrations = fs::read_dir(dir)\n    .unwrap()\n    .filter_map(|e| e.ok())\n    .any(|e| e.path().is_dir());\nassert!(has_migrations, \"no migration folders inside ./migrations\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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)"],"tags":["rust","proc-macro","compile-time","diesel","migrations"],"backgroundTag":"internal-invariant-violation","analyzedSha":"6fa6ed01b24b24248ab2a611698d0a7c6a2e9120","analyzedAt":"2026-09-07T01:50:13.074Z","contentChangedAt":"2026-09-07T01:50:13.074Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}