JamesNK/Newtonsoft.Json · error · JsonException

Could not resolve schema reference

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).

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

• Invalid JSON schema type
• Property has already been defined in schema.
• Unexpected contract type
• Unresolved circular reference for type
• Newtonsoft.Json serialization is not compatible with…

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

Appendix: 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)