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

failed to read query file at {}: {}

Error message

failed to read query file at {}: {}

What it means

`read_file_src` loads the contents of a query file referenced by `*_file!` macros at compile time. After resolving the path, it calls `fs::read_to_string`; if that fails (file missing, permission denied, not valid UTF-8), the error is wrapped with this message including the resolved path and the OS error. This is a compile-time error from the macro expansion.

Source

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

                    .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,
            format!(
                "failed to read query file at {}: {}",
                file_path.display(),
                e
            ),
        )
    })
}

View on GitHub (pinned to 03af8bcc57)

Solutions

1. Verify the file exists at the path relative to the crate's manifest directory (Cargo.toml); fix the path string
2. Check file permissions and that the file is valid UTF-8 text
3. In workspaces, confirm which crate the macro compiles in and adjust the relative path accordingly
4. Check filename case exactly matches (CI/Linux are case-sensitive)

Example fix

// before (file not at that location relative to manifest dir)
let q = query_file!("sql/get_user.SQL");
// after
let q = query_file!("src/queries/get_user.sql"); // exact, existing path

let p = std::path::Path::new(env!("CARGO_MANIFEST_DIR")).join("src/queries/get_user.sql");
std::fs::read_to_string(p.canonicalize().expect("query file missing")).expect("query file unreadable or not UTF-8");

When it happens

Trigger: `query_file!`/`query_as!` referencing a .sql file that does not exist at the resolved location, is unreadable (permissions), or contains invalid UTF-8; path resolved relative to the wrong crate because of workspace layout.

Common situations: Typo in the file path in the macro; file deleted or moved after writing the macro; building from a different crate in a workspace where the relative path no longer points at the file; case-sensitivity mismatch on Linux CI after developing on a case-insensitive macOS.

Related errors

• absolute paths will only work on the current machine
• paths relative to the current file's directory are not curre
• expected exactly 1 column, got {}
• query file path cannot be represented as a string
• Cannot use both flatten and json

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