sipeed/picoclaw · error

failed to load MCP config schema: %w

Error message

failed to load MCP config schema: %w

What it means

loadMCPConfigSchema parses the schema embedded in the binary (mcpConfigSchemaJSON constant) once via sync.Once (helpers.go:166-177). This error means the baked-in schema string is itself invalid JSON Schema — a build/source defect, not something user config or environment can cause. Every validated save passes through here.

Source

Thrown at cmd/picoclaw/internal/mcp/helpers.go:156

	for name, server := range cfg.Tools.MCP.Servers {
		if server.Type != "" {
			server.Type = config.NormalizeMCPTransportType(server.Type)
		}
		clone.Tools.MCP.Servers[name] = server
	}

	return &clone
}

func validateConfigDocument(data []byte) error {
	var instance map[string]any
	if err := json.Unmarshal(data, &instance); err != nil {
		return fmt.Errorf("failed to decode serialized config: %w", err)
	}

	schema, err := loadMCPConfigSchema()
	if err != nil {
		return fmt.Errorf("failed to load MCP config schema: %w", err)
	}

	if err := schema.Validate(instance); err != nil {
		return fmt.Errorf("config validation failed: %w", err)
	}

	return nil
}

func loadMCPConfigSchema() (*jsonschema.Resolved, error) {
	mcpConfigSchemaOnce.Do(func() {
		var schema jsonschema.Schema
		if err := json.Unmarshal([]byte(mcpConfigSchemaJSON), &schema); err != nil {
			errMcpConfigSchema = err
			return
		}
		mcpConfigSchema, errMcpConfigSchema = schema.Resolve(nil)
	})

View on GitHub (pinned to 49183d7e8d)

Solutions

1. Restore/fix the embedded schema constant in cmd/picoclaw/internal/mcp/helpers.go
2. Run the mcp package tests (go test ./cmd/picoclaw/...) after any schema change before building

if err := saveCmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "failed to load MCP config schema") {
		// schema is embedded in the binary — this indicates a broken build;
		// rebuild from a clean checkout rather than tweaking config
		return fmt.Errorf("picoclaw build defect: embedded schema invalid: %w", err)
	}
	return err
}

When it happens

Trigger: Editing mcpConfigSchemaJSON in helpers.go and introducing a JSON syntax error or an unresolvable $ref; a corrupted source tree producing a broken build.

Common situations: Contributors extending the config schema without running the package tests.

Related errors

• config is nil
• failed to serialize config: %w
• failed to decode serialized config: %w
• feishu channel is not supported on 32-bit architectures (arm
• session not found

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/1fd0fac3cd6498b6. Report an issue: GitHub.