transact-rs/sqlx · error · syn::Error

query file path cannot be represented as a string

Error message

query file path cannot be represented as a string

What it means

When a `*_file!` macro canonicalizes the query file path to embed source-location info, the resulting `Path` must be convertible to a UTF-8 `str`. If the canonicalized path contains invalid Unicode (e.g. non-UTF-8 bytes in directory names), `path.to_str()` returns `None` and the macro errors with this message at compile time.

Source

Thrown at sqlx-macros-core/src/query/input.rs:130

impl QuerySrc {
    /// If the query source is a file, read it to a string. Otherwise return the query string.
    fn resolve(self, source_span: Span) -> syn::Result<String> {
        match self {
            QuerySrc::String(string) => Ok(string),
            QuerySrc::File(file) => read_file_src(&file, source_span),
        }
    }

    fn file_path(&self, source_span: Span) -> syn::Result<Option<String>> {
        if let QuerySrc::File(ref file) = *self {
            let path = crate::common::resolve_path(file, source_span)?
                .canonicalize()
                .map_err(|e| syn::Error::new(source_span, e))?;

            Ok(Some(
                path.to_str()
                    .ok_or_else(|| {
                        syn::Error::new(
                            source_span,
                            "query file path cannot be represented as a string",
                        )
                    })?
                    .to_string(),
            ))
        } else {
            Ok(None)
        }
    }
}

fn read_file_src(source: &str, source_span: Span) -> syn::Result<String> {
    let file_path = crate::common::resolve_path(source, source_span)?;

    fs::read_to_string(&file_path).map_err(|e| {
        syn::Error::new(
            source_span,

View on GitHub (pinned to 03af8bcc57)

Solutions

1. Rename the offending directories/files so the full path is valid UTF-8 (ASCII is safest)
2. Move the project (or the .sql files) to a path with only standard characters
3. Regenerate/restore the path if it was corrupted by a tool or cache

Example fix

// before: project at /home/usér/pröject → canonicalize() yields non-UTF-8 bytes
// after: move project to an ASCII path
// /home/user/project, then:
let q = query_file!("src/queries/get_user.sql");

let p = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join(rel);
let canon = p.canonicalize().expect("query file must exist");
assert!(canon.to_str().is_some(), "query file path must be valid UTF-8");

When it happens

Trigger: Compiling `query_file!`/`query_as_file!` where the canonicalized query file path includes non-UTF-8 characters — unusual byte sequences in directory names, locale-specific encoded filenames.

Common situations: Project checked out in a directory whose name contains non-UTF-8 bytes; filesystems with legacy encodings; CI caches with mangled paths.

Related errors

• absolute paths will only work on the current machine
• paths relative to the current file's directory are not curre
• failed to read query file at {}: {}
• expected exactly 1 column, got {}
• unimplemented!()

AI-assisted analysis of transact-rs/sqlx@03af8bcc57 (2026-09-03). Data as JSON: /api/errors/8b5f6c54d3a7ddc7. Report an issue: GitHub.