risingwavelabs/risingwave · error · Error

need url to be a file or a http based, got {url}

Error message

need url to be a file or a http based, got {url}

What it means

Error::UnsupportedUrl is raised by the JSON schema $ref resolver in JsonRef::deref (src/connector/codec/src/decoder/json/mod.rs:151). When a JSON schema contains a `$ref` pointing to an external document, the resolver only supports fetching it via `http`/`https` or reading it via the `file` scheme; any other URL scheme produces this error naming the offending URL.

Source

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

    Request { url: String, source: reqwest::Error },
    #[error("schema from {url} not valid JSON")]
    SchemaNotJsonSerde {
        url: String,
        source: serde_json::Error,
    },
    #[error(
        "ref `{ref_string}` cannot be resolved as a pointer, and `{ref_fragment}` cannot be found in the schema"
    )]
    JsonRefPointerNotFound {
        ref_string: String,
        ref_fragment: String,
    },
    #[error("json ref error")]
    JsonRef {
        #[from]
        source: std::io::Error,
    },
    #[error("need url to be a file or a http based, got {url}")]
    UnsupportedUrl { url: String },
    #[error(transparent)]
    Uncategorized(
        #[from]
        #[backtrace]
        anyhow::Error,
    ),
}

type Result<T, E = Error> = std::result::Result<T, E>;

#[derive(Debug)]
pub struct JsonRef {
    schema_cache: HashMap<String, Value>,
}

impl JsonRef {
    fn new() -> JsonRef {

View on GitHub (pinned to 6469eb736d)

Solutions

1. Rewrite the `$ref` to an absolute `http://` or `https://` URL that RisingWave can fetch
2. Serve the referenced schema over a local HTTP endpoint or place it at a `file:///abs/path.json` URL accessible to the RisingWave node
3. Inline the referenced definition into the schema so no external `$ref` remains
4. Check the resolved URL scheme by printing it; ensure `Url::join` of the relative ref against the retrieval_url yields http/https/file

Example fix

// before
{"$ref": "urn:myorg:schemas:order"}
// after
{"$ref": "https://schema-registry.example.com/schemas/order.json"}

use url::Url;
fn ref_url_supported(ref_string: &str, base: &Url) -> bool {
    base.join(ref_string)
        .ok()
        .map(|u| matches!(u.scheme(), "http" | "https" | "file"))
        .unwrap_or(false)
}

When it happens

Trigger: A `CREATE SOURCE ... FORMAT PLAIN ENCODE JSON` (or JSON schema registry-based) declaration whose schema document contains `$ref` values that resolve to a URL with a scheme other than file/http/https, e.g. `urn:`, `data:`, `ftp:`, or a relative `$ref` joined against a base retrieval_url with an unsupported scheme.

Common situations: Users register a JSON schema exported from a tool that emits `urn:uuid:...` or `data:application/json,...` refs; a `$ref` to a schema served only over a private registry scheme; Kafka Confluent Schema Registry refs copied with custom scheme handlers.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• could not convert url {} to file path
• invalid credentials_url scheme '{}', only file://, s3://, an
• support negative scale for arrow decimal
• failed to parse meta address `{1}`: {0}
• parse error for url {url}

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