risingwavelabs/risingwave · error

could not convert url {} to file path

Error message

could not convert url {} to file path

What it means

During `$ref` dereferencing in JsonRef::deref (src/connector/codec/src/decoder/json/mod.rs:140), a ref whose scheme is `file` is converted with Url::to_file_path(). If the file URL cannot be mapped to a platform file path, an anyhow error `could not convert url {url} to file path` is returned. This happens when Url::to_file_path is called on a URL that is syntactically a file URL but not convertible (e.g. a relative path that was never made absolute, or a Windows-style path without a host understood on Unix).

Source

Thrown at src/connector/codec/src/decoder/json/mod.rs:141

            let ref_url = base_url.join(ref_string).into_url_parse(ref_string)?;
            let mut ref_url_no_fragment = ref_url.clone();
            ref_url_no_fragment.set_fragment(None);
            let url_schema = ref_url_no_fragment.scheme();
            let ref_no_fragment = ref_url_no_fragment.to_string();

            let mut schema = match self.schema_cache.get(&ref_no_fragment) {
                Some(cached_schema) => cached_schema.clone(),
                None => {
                    if url_schema == "http" || url_schema == "https" {
                        reqwest::get(ref_url_no_fragment.clone())
                            .await
                            .into_request(&ref_no_fragment)?
                            .json()
                            .await
                            .into_request(&ref_no_fragment)?
                    } else if url_schema == "file" {
                        let file_path = ref_url_no_fragment.to_file_path().map_err(|_| {
                            anyhow::anyhow!(
                                "could not convert url {} to file path",
                                ref_url_no_fragment
                            )
                        })?;
                        let file =
                            fs::File::open(file_path).into_schema_from_file(&ref_no_fragment)?;
                        serde_json::from_reader(file)
                            .into_schema_not_json_serde(ref_no_fragment.clone())?
                    } else {
                        return Err(Error::UnsupportedUrl {
                            url: ref_no_fragment,
                        });
                    }
                }
            };

            if !self.schema_cache.contains_key(&ref_no_fragment) {
                self.schema_cache

View on GitHub (pinned to 6469eb736d)

Solutions

1. Use an absolute file URL with three slashes: `file:///absolute/path/schema.json`
2. If running on Linux, convert Windows-style file URLs to POSIX absolute paths
3. Inline the referenced schema to avoid file resolution entirely
4. Verify with `Url::parse(...).to_file_path()` locally that the URL converts before using it in RisingWave

Example fix

// before
{"$ref": "file://schemas/order.json"}
// after
{"$ref": "file:///etc/risingwave/schemas/order.json"}

use url::Url;
fn file_url_to_path(ref_url: &Url) -> Option<std::path::PathBuf> {
    if ref_url.scheme() != "file" { return None; }
    ref_url.to_file_path().ok()
}

When it happens

Trigger: JsonRef::deref resolves a `$ref` whose base_url joined with the ref string yields a `file` scheme URL on which `Url::to_file_path()` fails — typically a relative file URL like `file:relative/path.json` (no leading slash / no authority) rather than `file:///abs/path.json`.

Common situations: Using a relative `$ref` like `common.json` with a retrieval_url that itself is a `file:relative/...` style URL; supplying a Windows path `file://C:/schemas/x.json` on a Linux node; missing a slash in a `file://` URL.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• need url to be a file or a http based, got {url}
• failed to parse meta address `{1}`: {0}
• parse error for url {url}
• s3 url {location} should have a '/' at the start of path.
• credentials_url must be a valid URL (s3://, file://) or an a

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/fa6886f2385bbaa0. Report an issue: GitHub.