JamesNK/Newtonsoft.Json · error · JsonException

Could not resolve schema reference '{0}'.

Error message

Could not resolve schema reference '{0}'.

What it means

Thrown by JsonSchemaBuilder.ResolveReferences when a $ref (or extends) pointer cannot be resolved: it is not found in the resolver's loaded schemas and, for '#'-prefixed location references, the JSON pointer walk through the root document failed (the target path does not exist in the schema document).

Source

Thrown at Src/Newtonsoft.Json/Schema/JsonSchemaBuilder.cs:152

                                    currentToken = null;
                                }
                            }

                            if (currentToken == null)
                            {
                                break;
                            }
                        }

                        if (currentToken != null)
                        {
                            resolvedSchema = BuildSchema(currentToken);
                        }
                    }

                    if (resolvedSchema == null)
                    {
                        throw new JsonException("Could not resolve schema reference '{0}'.".FormatWith(CultureInfo.InvariantCulture, schema.DeferredReference));
                    }
                }

                schema = resolvedSchema;
            }

            if (schema.ReferencesResolved)
            {
                return schema;
            }

            schema.ReferencesResolved = true;

            if (schema.Extends != null)
            {
                for (int i = 0; i < schema.Extends.Count; i++)
                {
                    schema.Extends[i] = ResolveReferences(schema.Extends[i]);

View on GitHub (pinned to 4f73e74372)

Solutions

1. Share one JsonSchemaResolver instance across all JsonSchema.Read/Parse calls so referenced ids are registered.
2. Verify the $ref target exists in the document (correct JSON pointer like #/definitions/foo).
3. Load referenced external schemas before the schema that points to them.

Example fix

// before
var s1 = JsonSchema.Parse("{\"id\":\"root\",\"items\":{\"$ref\":\"#missing\"}}");
// after
var s1 = JsonSchema.Parse("{\"id\":\"root\",\"definitions\":{\"i\":{}},\"items\":{\"$ref\":\"#/definitions/i\"}}");

static JsonSchemaResolver LoadAll(IEnumerable<string> schemaJsons)
{
    var resolver = new JsonSchemaResolver();
    foreach (var json in schemaJsons) JsonSchema.Parse(json, resolver);
    return resolver;
}

try { JsonSchema.Parse(json, resolver); }
catch (JsonException ex) when (ex.Message.StartsWith("Could not resolve schema reference"))
{ /* $ref target missing; load referenced schema or fix the pointer */ }

When it happens

Trigger: Loading a JSON Schema whose $ref points to a non-existent id or JSON pointer. Examples: JsonSchema.Parse("{\"$ref\":\"#unknown\"}") (pointer target missing), or a $ref to an external id that was never registered with the shared JsonSchemaResolver.

Common situations: Splitting a schema across files but not sharing a JsonSchemaResolver between reads; typos in $ref pointers; renaming a definition without updating references; cross-document $ref where the referenced document was not loaded first.

Related errors

• Property {0} has already been defined in schema.
• Invalid JSON schema type: {0}
• Unresolved circular reference for type '{0}'. Explicitly def
• Unexpected contract type: {0}
• Newtonsoft.Json serialization is not compatible with trimmin

AI-assisted analysis of JamesNK/Newtonsoft.Json@4f73e74372 (2026-08-07). Data as JSON: /api/errors/8b41c4206e5f9097. Report an issue: GitHub.