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

Re-run picoclaw mcp test 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 picoclaw's default server probe (used by picoclaw mcp test). The probe builds a one-server Manager config, forces server.Enabled = true, and calls LoadFromMCPConfig; that call reported success, yet Manager.GetServer(name) found no registered connection. Because the manager returns an aggregated error when the only enabled server fails to connect (pkg/mcp/manager.go:262), a plain connect failure surfaces as a different wrapped error — reaching this branch means a connection was not stored despite a successful load: an internal inconsistency, a race (manager closing mid-load), or version skew between the CLI and pkg/mcp.

Source

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

) (probeResult, 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 probeResult{}, err
	}

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

	return probeResult{ToolCount: len(conn.Tools)}, nil
}

func confirmOverwrite(r io.Reader, w io.Writer, name string) (bool, error) {
	if _, err := fmt.Fprintf(w, "MCP server %q already exists. Overwrite? [y/N]: ", name); err != nil {
		return false, err
	}

	var answer string
	if _, err := fmt.Fscanln(r, &answer); err != nil {
		if errors.Is(err, io.EOF) {
			return false, nil
		}
		return false, err
	}

View on GitHub (pinned to 49183d7e8d)

Solutions

Re-run picoclaw mcp test <name> once to rule out a transient race
Run picoclaw mcp show <name> to cross-check registration and check manager logs for connect/registration lines
Reinstall or upgrade picoclaw so the CLI helpers and pkg/mcp manager come from the same build
If reproducible with a minimal config, file a picoclaw bug including 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

result, err := serverProbe(ctx, name, server, workspace)
if err != nil {
  if isNotRegisteredError(err) {
    // transient/internal: retry once with a fresh context before surfacing
    result, err = serverProbe(ctx, name, server, workspace)
  }
  if err != nil {
    return fmt.Errorf("probe %s: %w", name, err)
  }
}

Prevention

Keep picoclaw in one piece: upgrade the whole binary rather than mixing versions
Do not run probes while the enclosing app is shutting down
Treat this message as a bug indicator, not a config problem — capture logs when it appears

When it happens

Trigger: ConnectServer succeeding but the connection not being stored under the exact probe name (concurrent Close during load, registration-key mismatch); mixing picoclaw versions so manager registration semantics differ from the CLI helper's expectations.

Common situations: Rare. Seen when the probe's manager is torn down concurrently, after partial upgrades that leave cmd/picoclaw and pkg/mcp from different releases, or after a manager refactor that changes how servers are registered.

Related errors

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