Tencent/WeKnora · error

failed to generate schema: %v

Error message

failed to generate schema: %v

What it means

GenerateSchema[T] builds a JSON schema for the tool's input type using jsonschema.For[T](nil). If schema generation fails (e.g. the type uses constructs the generator cannot represent), it panics. This runs when tool definitions are built, so it is effectively a startup failure for the affected tool.

Source

Thrown at internal/utils/json.go:24

	jsonschema "github.com/google/jsonschema-go/jsonschema"
)

// ToJSON converts a value to a JSON string
func ToJSON(v interface{}) string {
	json, err := json.Marshal(v)
	if err != nil {
		return ""
	}
	return string(json)
}

// GenerateSchema generates JSON schema for type T and returns it as a map
// This is optimized to avoid unnecessary serialization/deserialization
func GenerateSchema[T any]() json.RawMessage {
	schema, err := jsonschema.For[T](nil)
	if err != nil {
		panic(fmt.Sprintf("failed to generate schema: %v", err))
	}

	// Convert schema to map directly through JSON marshaling
	// This is necessary because the schema object doesn't expose its internal structure
	schemaBytes, err := json.Marshal(schema)
	if err != nil {
		panic(fmt.Sprintf("failed to marshal schema: %v", err))
	}

	return schemaBytes
}

View on GitHub (pinned to 988cbb0330)

Solutions

1. Simplify or replace unsupported field types in the tool's input struct with JSON-representable types
2. Add struct tags (jsonschema:/json:) or a custom GenerateSchema override to guide generation
3. Pin/upgrade the jsonschema library to a version that supports the type in question
4. Wrap GenerateSchema at startup so the offending tool and type are named in logs

Example fix

// before
type input struct { Callback func(string) error `json:"callback"` }
// after
type input struct { CallbackID string `json:"callback_id"` } // representable type

// sanity-check the input type is JSON-representable before tool init
var probe T
b, err := json.Marshal(probe)
if err != nil { return fmt.Errorf("type %T not JSON-representable: %w", probe, err) }

func schemaGeneratable[T any]() (ok bool) {
    defer func() { _ = recover() }()
    _ = utils.GenerateSchema[T]()
    return true
}

func schemaSafe[T any]() (raw json.RawMessage, err error) {
    defer func() { if r := recover(); r != nil { err = fmt.Errorf("schema panic: %v", r) } }()
    return utils.GenerateSchema[T](), nil
}

When it happens

Trigger: Declaring a tool input struct that invopop/jsonschema cannot generate a schema for: unsupported field types (func, chan, complex), cycles without ref handling, invalid map key types, or generics instantiation producing an unsupported shape. Triggered by dataAnalysisTool, dataSchemaTool, databaseQueryTool, queryKnowledgeGraphTool, editSandboxFileTool, listSandboxFilesTool.

Common situations: Adding a field of an exotic type to a tool's request struct; a custom type without jsonschema-friendly tagging; upgrading the jsonschema library and hitting a new/changed limitation; embedding interfaces in tool parameter structs.

Related errors

• failed to marshal schema: %v
• failed to list tools: %w
• failed to generate JWT secret: %v
• im: duplicate command registration: %s
• api-key policy declared for non-existent route(s): %s

AI-assisted analysis of Tencent/WeKnora@988cbb0330 (2026-09-02). Data as JSON: /api/errors/b668e41a80f55856. Report an issue: GitHub.