Skill files were not properly embedded at build time. Please

Error message

Skill files were not properly embedded at build time. Please report this as a bug.

What it means

write_skill_files embeds the skill assets (SKILL.md, references, examples) into the binary at compile time via the SKILL_FILES table. Before writing anything it verifies no embedded blob is empty; an empty blob means the compile-time embedding never happened (missing or zero-length asset files at build time), which is a build/packaging defect. Failing here prevents writing empty files to the user's disk.

Source

Thrown at crates/but/src/command/skill/mod.rs:985

/// Prepare SKILL.md content with version injection and validate all files
fn prepare_skill_content(version: &str) -> Result<String> {
    // Validate all embedded files are valid UTF-8
    let skill_content = std::str::from_utf8(SKILL_MD).context("SKILL.md is not valid UTF-8")?;
    std::str::from_utf8(CONCEPTS_MD).context("concepts.md is not valid UTF-8")?;
    std::str::from_utf8(EXAMPLES_MD).context("examples.md is not valid UTF-8")?;
    std::str::from_utf8(REFERENCE_MD).context("reference.md is not valid UTF-8")?;

    // Inject version into SKILL.md
    Ok(inject_version(skill_content, version))
}

/// Write the bundled skill files into `install_path`, creating the directory
/// structure as needed and injecting the CLI version into SKILL.md. Returns the
/// version that was written.
pub(crate) fn write_skill_files(install_path: &std::path::Path) -> Result<&'static str> {
    if SKILL_FILES.iter().any(|f| f.content.is_empty()) {
        anyhow::bail!(
            "Skill files were not properly embedded at build time. Please report this as a bug."
        );
    }

    // Prepare all content before writing (validate UTF-8 and inject version)
    let version = option_env!("VERSION").unwrap_or("dev");
    let skill_md_content = prepare_skill_content(version)?;

    let references_dir = install_path.join("references");
    std::fs::create_dir_all(&references_dir).with_context(|| {
        format!(
            "Failed to create skill directory at {}. Check that you have write permissions for this location.",
            install_path.display()
        )
    })?;

    for file in skill_files_in_write_order() {
        let file_path = file.get_install_path(install_path);

View on GitHub (pinned to caf1f223d3)

Solutions

Report the bug to GitButler including the binary's version
Rebuild from a clean complete checkout: cargo clean && cargo build
Fall back to an official GitButler release binary
Verify the skill asset files exist and are non-empty under crates/but/skill before compiling

Defensive patterns

Strategy: try-catch

Try / catch

match write_skill_files(&install_path) {
    Err(e) if e.to_string().contains("not properly embedded") => {
        // build defect: do not retry; report binary version and rebuild
    }
    other => other,
}

Prevention

Add a CI smoke test that runs `but skill install --path` on release builds
Assert SKILL_FILES assets are non-empty in a build-time unit test
Package only from full checkouts, never stripped tarballs

When it happens

Trigger: Building crates/but from a source tree where the skill asset files under crates/but/skill are missing or zero-length at compile time; packaging scripts that strip assets; a corrupted cargo cache reusing stale artifacts.

Common situations: Nightly packaging jobs, source tarballs created without the skill assets, sparse git checkouts excluding the asset directory, downstream distro builds.

Related errors

AI-assisted analysis of gitbutlerapp/gitbutler@caf1f223d3 (2026-08-20). Data as JSON: /api/errors/21992a709de59832. Report an issue: GitHub.