risingwavelabs/risingwave · error · Error

json ref error

Error message

json ref error

What it means

Error::JsonRef wraps a std::io::Error (via #[from]) raised while resolving JSON schema $ref references. The message is generic; the underlying IO error (e.g. failing to read a referenced local file) carries the specifics.

Source

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

        source: url::ParseError,
    },
    #[error("schema from {url} not valid JSON")]
    SchemaNotJson { url: String, source: std::io::Error },
    #[error("request error")]
    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 {

View on GitHub (pinned to 6469eb736d)

Solutions

1. Inspect the chained io::Error source for the real cause (path, permissions).
2. Make all $ref targets resolvable within the single schema document (inline definitions).
3. Ensure any referenced files exist and are readable relative to the RisingWave process.
4. Use http-based schema URLs if references live remotely.

Example fix

// before
{"$ref": "common_types.json#/Address"}  // common_types.json not accessible
// after
{"$ref": "#/definitions/Address"} with Address inlined in the same document

const fs = require('fs');
for (const p of collectRefFilePaths(schema)) {
  if (!fs.existsSync(p)) throw new Error(`$ref target file missing: ${p}`);
}

match res {
  Err(Error::JsonRef { source }) => eprintln!("io failure during $ref resolution: {source}"),
  other => other?,
}

When it happens

Trigger: During $ref resolution the resolver performs IO (such as reading a referenced file) and the read fails, converting into this variant automatically via #[from].

Common situations: $ref pointing to a relative file path that cannot be opened from the process working directory; permission or missing-file errors during reference resolution.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• could not open schema from {filename}
• I/O error: {0}
• I/O error: {0}
• parse error for url {url}
• ref `{ref_string}` cannot be resolved as a pointer, and `{re

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