siyuan-note/siyuan · error

invalid frontend capability [%s]: %w

Error message

invalid frontend capability [%s]: %w

What it means

After id and description checks pass, capability.go calls tools.CompileToolValidator on a synthetic Tool built from the frontend capability's InputSchema/OutputSchema. If compilation fails (invalid JSON Schema, unsupported keywords, schema does not compile to a validator), the error is wrapped with 'invalid frontend capability [<id>]: %w' and returned.

Source

Thrown at kernel/agent/capability.go:232

	for _, frontend := range frontendCapabilities {
		if !validFrontendCapabilityID(frontend.ID) {
			return nil, fmt.Errorf("invalid frontend capability ID: %s", frontend.ID)
		}
		if strings.TrimSpace(frontend.Description) == "" {
			return nil, fmt.Errorf("frontend capability description is required: %s", frontend.ID)
		}
		if !capabilityAllowed(frontend.ID, accessContext) {
			continue
		}
		validationTool := &tools.Tool{
			Name:         frontendCapabilityModelName(frontend.ID),
			Description:  frontend.Description,
			InputSchema:  frontend.InputSchema,
			OutputSchema: frontend.OutputSchema,
		}
		validator, err := tools.CompileToolValidator(validationTool)
		if err != nil {
			return nil, fmt.Errorf("invalid frontend capability [%s]: %w", frontend.ID, err)
		}
		source := "native"
		if strings.HasPrefix(frontend.ID, "plugin/frontend/") {
			source = "plugin"
		}
		effects := tools.ToolEffects{}
		if frontend.Effects != nil {
			effects = *frontend.Effects
		}
		registration := &capabilityRegistration{
			ID:              frontend.ID,
			ModelName:       validationTool.Name,
			Title:           frontend.Title,
			Description:     frontend.Description,
			Source:          source,
			OwnerID:         frontend.OwnerID,
			OwnerName:       frontend.OwnerName,
			Runtime:         "browser",

View on GitHub (pinned to 251596fc0d)

Solutions

1. Read the wrapped error — it is the compiler's specific complaint about the schema.
2. Validate the InputSchema/OutputSchema against JSON Schema draft used by tools.CompileToolValidator before submitting the capability.
3. Strip unsupported keywords and simplify the schema to primitive types first; add complexity incrementally.
4. Use the same ToolInputSchema shape as native kernel tools as a reference template.

Example fix

// before
cap := FrontendCapability{ID: id, Description: 'x', InputSchema: map[string]any{'type': 'obj'}} // typo
// after
import 'github.com/siyuan-note/siyuan/kernel/tools'
cap := FrontendCapability{ID: id, Description: 'x',
    InputSchema: map[string]any{'type': 'object', 'properties': map[string]any{'q': map[string]any{'type':'string'}}, 'required': []string{'q'}},
}
if _, err := tools.CompileToolValidator(&tools.Tool{Name: 't', InputSchema: cap.InputSchema}); err != nil { return err }

validator, err := tools.CompileToolValidator(&tools.Tool{Name: 'tmp', InputSchema: frontend.InputSchema, OutputSchema: frontend.OutputSchema})
if err != nil { return fmt.Errorf('schema rejected before submit: %w', err) }

if err := buildCapabilitySet(...); err != nil {
    if strings.Contains(err.Error(), 'invalid frontend capability') { /* read wrapped schema error, fix and retry */ }
    return err
}

When it happens

Trigger: A frontend capability supplies an InputSchema or OutputSchema that is not a valid JSON Schema (wrong 'type' value, malformed 'properties', unsupported keyword for the compiler, $ref that cannot be resolved, or array/object schemas missing required fields).

Common situations: Plugin author writes a JSON Schema by hand and mistypes a keyword; schema uses draft-07-only features not supported by the kernel's compiler; OutputSchema declared but not a valid schema object; properties typed as strings instead of schema objects; enum/array mixed incorrectly.

Related errors

• invalid frontend capability ID: %s
• frontend capability description is required: %s
• registerCapability requires 3 arguments: name, config, handl
• capability name must not be empty
• config.description must not be empty

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