What causes "schema exceeds %d bytes" in siyuan-note/siyuan?

Reduce the schema size below 1 MiB: replace long inline enum lists with a pattern/format, move repeated sub-schemas into $defs and reference them with $ref, and strip descriptions/examples.

siyuan-note/siyuan · error

schema exceeds %d bytes

Error message

schema exceeds %d bytes

What it means

Thrown by resolveToolSchema when a tool's marshaled input or output JSON schema is larger than maxToolSchemaBytes (1 MiB, 1<<20). The guard runs before jsonschema parsing so a pathologically large schema cannot exhaust memory or CPU during Resolve/Validate. It protects the MCP server from malicious or buggy tool definitions submitted by clients/plugins.

Source

Thrown at kernel/mcp/tools/validation.go:80

	return &ToolValidator{
		input:           input,
		output:          output,
		validationSlots: make(chan struct{}, toolValidationConcurrency),
	}, nil
}

func resolveToolSchema(schema ToolSchema, requireObject bool) (*jsonschema.Resolved, error) {
	if schema.Raw != nil {
		if err := validateJSONComplexity(schema.Raw, maxToolSchemaDepth, maxToolSchemaNodes); err != nil {
			return nil, err
		}
	}
	data, err := json.Marshal(schema)
	if err != nil {
		return nil, err
	}
	if len(data) > maxToolSchemaBytes {
		return nil, fmt.Errorf("schema exceeds %d bytes", maxToolSchemaBytes)
	}
	var raw any
	if err = json.Unmarshal(data, &raw); err != nil {
		return nil, err
	}
	if err = validateJSONComplexity(raw, maxToolSchemaDepth, maxToolSchemaNodes); err != nil {
		return nil, err
	}
	if requireObject {
		if err = validateParamHeaderAnnotations(raw); err != nil {
			return nil, err
		}
	}
	var parsed jsonschema.Schema
	if err = json.Unmarshal(data, &parsed); err != nil {
		return nil, err
	}
	if requireObject && parsed.Type != "object" {

View on GitHub (pinned to 251596fc0d)

Solutions

Reduce the schema size below 1 MiB: replace long inline enum lists with a pattern/format, move repeated sub-schemas into $defs and reference them with $ref, and strip descriptions/examples.
If the schema legitimately needs to be large, reconsider the tool surface — split one giant tool into several narrower tools with smaller schemas.
Validate schema size client-side before sending: marshal the schema and assert len(data) <= 1<<20.
Check for accidental duplication (e.g., the same $defs block copied into multiple tools).

Example fix

// before: schema with huge inline enum
{
  "type": "object",
  "properties": { "country": { "type": "string", "enum": [/* 10000 entries */] } }
}
// after: constrain via format/pattern, or fetch the list at runtime
{
  "type": "object",
  "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$" } }
}

Defensive patterns

Strategy: validation

Validate before calling

data, err := json.Marshal(schema)
if err != nil { return err }
if len(data) > 1<<20 {
    return fmt.Errorf("schema is %d bytes, max %d", len(data), 1<<20)
}

Prevention

Marshal and size-check every tool schema in a unit test before registering the tool.
Prefer $ref/$defs over inlining repeated sub-schemas to keep size down.
Avoid embedding large enum lists or example payloads in shipped schemas.

When it happens

Trigger: Registering an MCP tool (CompileToolValidator -> resolveToolSchema) whose InputSchema or OutputSchema, after json.Marshal, exceeds 1048576 bytes. Common with schemas embedding huge enums, long format regexes, or inlined $defs instead of references.

Common situations: A plugin auto-generates a tool schema from a large OpenAPI spec; a developer pastes a verbose JSON Schema with thousands of enum values; a tool schema accidentally inlines documentation strings or example payloads that bloat the payload past 1 MiB.

Related errors

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/a87bd30d229734c5. Report an issue: GitHub.