fixture structure verification failed: fixture paths must…

Error message

fixture structure verification failed: fixture paths must be valid UTF-8

What it means

Thrown by `entry_name()` during fixture structure verification when a directory entry's file name cannot be converted from OsString to String (non-UTF-8 bytes). Fixture verification requires all paths under the fixture tree to be valid UTF-8 so they can be treated as schema/asset names. It is wrapped with the 'fixture structure verification failed' prefix used by `inspect`.

Solutions

Find and rename or delete the offending non-UTF-8 file in the fixture directory (e.g. with `find . -name '*\x*'` or `convmv`)
Re-extract or re-copy the fixtures ensuring a UTF-8 filesystem locale (LANG/LC_ALL=C.UTF-8)
Regenerate the fixture set from the recording tool instead of hand-copying files

Defensive patterns

Strategy: validation

Validate before calling

for entry in fs::read_dir(fixtures_dir)? {
    let entry = entry?;
    if entry.file_name().to_str().is_none() {
        anyhow::bail!("non-UTF-8 fixture path: {:?}", entry.file_name());
    }
}

Type guard

fn valid_utf8_name(entry: &DirEntry) -> Option<&str> {
    entry.file_name().to_str()
}

Try / catch

match verify_fixture_tree(path) {
    Ok(report) => println!("{}", report),
    Err(e) if e.to_string().contains("valid UTF-8") => {
        eprintln!("Fixture tree has a non-UTF-8 filename; rename it and retry.");
    }
    Err(e) => return Err(e),
}

Prevention

Keep fixture filenames ASCII/UTF-8 only; lint the fixtures dir in CI
Extract fixture archives with a UTF-8 locale (LC_ALL=C.UTF-8)
Use `convmv` or `find -name '*\x*'` audits after copying fixtures across machines

When it happens

Trigger: `openlogi` fixture verify (via inspect or load_cassettes) walks a fixture directory containing a file or subdirectory whose name contains invalid UTF-8 bytes — common with files created on other filesystems/encodings or by archive extraction.

Common situations: Extracting a fixture tarball created with a non-UTF-8 locale; files copied from Windows with legacy codepage names; a stray file dropped into fixtures/ by a tool with raw-byte naming.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

AI-assisted analysis of AprilNEA/OpenLogi@e846e6f4b4 (2026-09-13). Data as JSON: /api/errors/586493fbc6f58845. Report an issue: GitHub.

Appendix: source

Thrown at crates/openlogi-cli/src/cmd/fixture/verify.rs:251

}

fn require_regular_file(entry: &DirEntry, asset: &str) -> Result<()> {
    let metadata = entry_metadata(entry, asset)?;
    if metadata.file_type().is_symlink() || !metadata.is_file() {
        bail!("fixture structure verification failed: {asset} must be a non-symlink regular file");
    }
    Ok(())
}

fn entry_metadata(entry: &DirEntry, asset: &str) -> Result<std::fs::Metadata> {
    fs::symlink_metadata(entry.path()).with_context(|| {
        format!("fixture structure verification failed: could not inspect {asset}")
    })
}

fn entry_name(entry: &DirEntry) -> Result<String> {
    entry.file_name().into_string().map_err(|_| {
        anyhow::anyhow!("fixture structure verification failed: fixture paths must be valid UTF-8")
    })
}

#[cfg(test)]
mod tests;

View on GitHub (pinned to e846e6f4b4)