siyuan-note/siyuan · error · Error

Agent capability name and description are required

Error message

Agent capability name and description are required

What it means

Plugin.addAgentCapability() throws 'Agent capability name and description are required' when options.name.trim() or options.description.trim() is empty. The name becomes part of the registered capability id ('plugin/frontend/<plugin>/<name>'), so empty values would produce an invalid id; the description is shown to the model and must not be blank.

Source

Thrown at app/src/plugin/index.ts:455

    }

    public addAgentCapability(options: {
        name: string,
        title?: string,
        description: string,
        inputSchema: Record<string, unknown>,
        outputSchema?: Record<string, unknown>,
        effects?: IAgentCapabilityEffects,
        actionEffects?: Record<string, IAgentCapabilityEffects>,
        handler: (args: Record<string, unknown>, app: App) => Promise<{
            result?: string;
            structuredContent?: unknown;
            error?: string;
        }>
    }): string {
        const name = options.name.trim();
        if (!name || !options.description.trim()) {
            throw new Error("Agent capability name and description are required");
        }
        const id = "plugin/frontend/" + encodeURIComponent(this.name) + "/" + encodeURIComponent(name);
        if (!this.agentCapabilities.some((capability) => capability.id === id)) {
            const generation = registerCapability({
                id,
                title: options.title,
                description: options.description,
                inputSchema: options.inputSchema,
                outputSchema: options.outputSchema,
                effects: options.effects,
                actionEffects: options.actionEffects,
                source: "plugin",
                ownerId: this.name,
                ownerName: this.displayName || this.name,
                handler: options.handler,
            });
            this.agentCapabilities.push({id, generation});
        }

View on GitHub (pinned to 251596fc0d)

Solutions

1. Validate name and description before calling addAgentCapability and skip registration if blank.
2. Provide non-empty defaults for name and description from the plugin manifest or i18n bundle.
3. Trim and assert length > 0 on both fields at the call site.
4. Surface the error to the plugin author during development via the plugin console.

Example fix

// before
this.addAgentCapability({name, description, inputSchema, handler});
// after
if (!name?.trim() || !description?.trim()) {
    console.warn('[plugin] skipping capability registration: empty name or description');
    return;
}
this.addAgentCapability({name: name.trim(), description: description.trim(), inputSchema, handler});

const name = options.name?.trim();
const description = options.description?.trim();
if (!name || !description) { console.warn('capability registration skipped: empty name/description'); return; }

function isValidCapabilityOptions(o: {name?: unknown; description?: unknown}): boolean {
    return typeof o.name === 'string' && o.name.trim().length > 0 &&
        typeof o.description === 'string' && o.description.trim().length > 0;
}

try { this.addAgentCapability(opts); }
catch (e) { if (/name and description are required/i.test(e.message)) return; throw e; }

When it happens

Trigger: A plugin calls this.addAgentCapability({...}) with name=' ', description='', or omits the field; user input used as the name/description without trimming; template literal that evaluated to empty.

Common situations: Plugin author forgot to localize the description; dynamically generated name from user input that was blank; refactor renamed the field but left a default empty string; plugin loaded before its i18n bundle resolved.

Related errors

• Failed to update agent session permission
• ${data.error.message}
• plugin [%s] not found
• registerCapability requires 3 arguments: name, config, handl
• capability name must not be empty

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