siyuan-note/siyuan · error

frontend capability description is required

Error message

frontend capability description is required: %s

What it means

buildCapabilitySet validates every frontend-provided capability before registering it as a tool. A capability whose Description field is empty or whitespace-only is rejected because the model-facing tool definition needs a usable description. The capability ID is included so the offending registration can be located.

Solutions

1. Set a non-empty Description on the frontend capability whose ID is named in the error
2. If the description comes from plugin metadata, fix the plugin's manifest/description source so it returns a real string
3. If a capability is not ready to describe, omit it from the frontendCapabilities list entirely instead of passing an empty description

Example fix

// before
{ID: "plugin/frontend/preview", Name: "preview", InputSchema: schema}
// after
{ID: "plugin/frontend/preview", Name: "preview", Description: "Render a live preview of the current block", InputSchema: schema}

if strings.TrimSpace(cap.Description) == "" {
    return fmt.Errorf("capability %s needs a description", cap.ID)
}

When it happens

Trigger: A frontend or plugin registers a capability with an empty Description field, e.g. passing {ID: "plugin/frontend/foo", Name: ..., InputSchema: ...} without Description into the capability list consumed by buildCapabilitySet.

Common situations: Plugin authors adding a new frontend capability but forgetting to fill in the Description; capability metadata built dynamically where a description lookup returns an empty string; JSON payloads from the frontend with a missing/empty description field.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• capability ID collision
• capability model name collision
• invalid frontend capability ID
• invalid frontend capability
• invalid session data

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

Appendix: source

Thrown at kernel/agent/capability.go:238

			OwnerName:     tool.OwnerName,
			Runtime:       runtime,
			Tool:          tool,
			Validator:     validator,
			InputSchema:   tool.InputSchema,
			OutputSchema:  tool.OutputSchema,
			AccessContext: accessContext,
		}
		if err := set.add(registration); err != nil {
			return nil, err
		}
	}

	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"
		}

View on GitHub (pinned to 9f775e8a12)