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

Reduce the schema: split the tool into multiple tools, trim unused properties, and collapse repeated subtrees into $defs with $ref.

siyuan-note/siyuan · error

schema exceeds bytes

Error message

schema exceeds %d bytes

What it means

resolveToolSchema enforces a hard size budget on tool schemas: the serialized schema must not exceed maxToolSchemaBytes (1 MiB). Oversized schemas are rejected before parsing because validating them would be expensive and they usually indicate a mis-generated schema. This protects the MCP tool registry from pathological inputs.

Solutions

Reduce the schema: split the tool into multiple tools, trim unused properties, and collapse repeated subtrees into $defs with $ref.
Remove any inlined payloads, sample data, or huge enum lists from the schema.
Check for accidental recursion/duplication in the code that builds the ToolSchema.
If the schema is genuinely large but valid, restructure the tool contract to accept narrower arguments.

Example fix

// before
// giant enum inlined for every property: 2 MB schema
Type: "string", Enum: allCountryCodes // repeated across 50 properties
// after
// single $def referenced everywhere
$ref: "#/definitions/CountryCode" // defined once, schema well under 1 MB

Defensive patterns

Strategy: validation

Validate before calling

if (JSON.stringify(toolSchema).length > 1048576) {
  throw new Error("tool schema exceeds 1 MiB before registration");
}

Prevention

Factor repeated schema subtrees into $defs + $ref instead of duplicating them.
Never inline sample payloads, large enums, or data blobs into tool schemas.
Split oversized tool contracts into multiple narrower tools.
Measure serialized schema size in CI when generating schemas programmatically.

When it happens

Trigger: CompileToolValidator is called with a tool whose InputSchema or OutputSchema serializes (json.Marshal of ToolSchema) to more than 1048576 bytes — typically enormous generated schemas, schemas embedding large enums/datasets, or schemas accidentally containing bulk data.

Common situations: Code generators emitting full API schemas (hundreds of properties, giant enums) into a single tool; schemas that accidentally inline sample payloads or documentation blobs; recursion in a schema builder duplicating subtrees.

Understand the failure class

Background: "File too large" / "file size exceeds limit" errors: why libraries cap file sizes and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/a87bd30d229734c5. Report an issue: GitHub.

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