What causes "server %q did not register a connection" in sipeed/picoclaw?

Re-run picoclaw mcp show once to rule out a transient race

server %q did not register a connection

Error message

server %q did not register a connection

What it means

An internal invariant in the show probe (defaultServerShowProbe, used by picoclaw mcp show). The probe forces Enabled=true on a single-server config, LoadFromMCPConfig succeeded, yet Manager.GetServer(name) found no connection. Note the show command already refuses disabled servers earlier and prints them without probing, and the manager aggregates connect failures into an error — so this branch indicates a load-registered-nothing inconsistency: a race such as the manager closing mid-load, or version skew between the CLI and pkg/mcp manager.

Source

Thrown at cmd/picoclaw/internal/mcp/show.go:56

) ([]toolDetail, error) {
	mgr := picomcp.NewManager()
	defer func() { _ = mgr.Close() }()

	server.Enabled = true
	mcpCfg := config.MCPConfig{
		ToolConfig: config.ToolConfig{Enabled: true},
		Servers: map[string]config.MCPServerConfig{
			name: server,
		},
	}

	if err := mgr.LoadFromMCPConfig(ctx, mcpCfg, workspacePath); err != nil {
		return nil, err
	}

	conn, ok := mgr.GetServer(name)
	if !ok {
		return nil, fmt.Errorf("server %q did not register a connection", name)
	}

	details := make([]toolDetail, 0, len(conn.Tools))
	for _, tool := range conn.Tools {
		details = append(details, toolDetail{
			Name:        tool.Name,
			Description: tool.Description,
			Parameters:  extractParameters(tool.InputSchema),
		})
	}
	return details, nil
}

func extractParameters(schema any) []paramDetail {
	schemaMap := normalizeSchema(schema)
	properties, ok := schemaMap["properties"].(map[string]any)
	if !ok || len(properties) == 0 {
		return nil

View on GitHub (pinned to 49183d7e8d)

Solutions

Re-run picoclaw mcp show <name> once to rule out a transient race
Check manager logs for connect/registration lines mentioning the server name
Reinstall or upgrade picoclaw so the CLI and pkg/mcp manager come from the same build
If reproducible, file a picoclaw bug with the server entry and logs

Defensive patterns

Strategy: try-catch

Type guard

func isNotRegisteredError(err error) bool {
  return err != nil && strings.Contains(err.Error(), "did not register a connection")
}

Try / catch

details, err := serverShowProbe(ctx, name, server, workspace)
if err != nil {
  if isNotRegisteredError(err) {
    details, err = serverShowProbe(ctx, name, server, workspace) // one retry for load/register races
  }
  if err != nil {
    return fmt.Errorf("failed to connect to MCP server %q: %w", name, err)
  }
}

Prevention

Upgrade picoclaw as a single build so CLI helpers and the manager stay in sync
Avoid probing during shutdown of the enclosing process
Report reproducible occurrences with logs — this branch signals an internal inconsistency

When it happens

Trigger: ConnectServer succeeding without the connection being stored under the exact name (concurrent Close during load); a picoclaw install mixing versions so manager registration semantics differ from the helper's assumption.

Common situations: Rare; typically around shutdown races, partial upgrades, or refactors of the manager registration path. Ordinary connection problems produce the 'failed to connect to MCP server' wrapper instead.

Related errors

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