risingwavelabs/risingwave · error · Error

ref `{ref_string}` cannot be resolved as a pointer, and `{re

Error message

ref `{ref_string}` cannot be resolved as a pointer, and `{ref_fragment}` cannot be found in the schema

What it means

Error::JsonRefPointerNotFound indicates a $ref in the JSON schema could not be resolved: it is neither a valid JSON pointer into the document, nor does the named fragment exist within the schema. The decoder cannot inline the referenced type and aborts schema conversion.

Source

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

    SchemaFromFile {
        filename: String,
        source: std::io::Error,
    },
    #[error("parse error for url {url}")]
    UrlParse {
        url: String,
        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,

View on GitHub (pinned to 6469eb736d)

Solutions

1. Inline all referenced definitions so the schema is self-contained (one JSON document).
2. Fix the $ref string to match an existing definition path in the schema (check spelling and pointer path).
3. Pre-process the schema with a bundler (e.g. json-schema-ref-parser) before feeding it to RisingWave.

Example fix

// before
{"type":"record","fields":[{"name":"addr","type":{"$ref":"#/definitions/Address"}}]}  // definitions/Address missing
// after
{"type":"record","fields":[{"name":"addr","type":{"type":"record","name":"Address","fields":[{"name":"city","type":"string"}]}}]}

const ref = findRefs(schema)[0];
if (ref?.startsWith('#')) {
  const frag = ref.slice(2).split('/');
  let node = schema;
  for (const k of frag) { node = node?.[k]; if (node === undefined) throw new Error(`unresolved $ref: ${ref}`); }
}

if let Err(Error::JsonRefPointerNotFound { ref_string, ref_fragment }) = res {
  eprintln!("inline or fix $ref '{ref_string}' (fragment '{ref_fragment}' missing)");
}

When it happens

Trigger: Loading a JSON schema containing "$ref": "#/definitions/Foo" (or a fragment ref) where definitions/Foo is absent, or a ref string that is not a valid JSON pointer and not resolvable to a fragment inside the loaded schema.

Common situations: Splitting a schema into multiple files and keeping cross-file $refs that this loader does not fetch; renaming definitions without updating refs; refs pointing to external URLs not resolvable as pointers.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• could not open schema from {filename}
• parse error for url {url}
• json ref error

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