lima-vm/lima · error

instance not registered

Error message

instance not registered

What it means

The MCP RunShellCommand tool returns this sentinel error when ToolSet.inst is nil — no instance registered. Shell commands execute in the guest by exec'ing ts.limactl against the registered instance (after translating the working directory), which is impossible without RegisterInstance.

Source

Thrown at pkg/mcp/toolset/shell.go:21

package toolset

import (
	"bytes"
	"context"
	"errors"
	"os/exec"

	"github.com/modelcontextprotocol/go-sdk/mcp"

	"github.com/lima-vm/lima/v2/pkg/mcp/msi"
)

func (ts *ToolSet) RunShellCommand(ctx context.Context,
	_ *mcp.CallToolRequest, args msi.RunShellCommandParams,
) (*mcp.CallToolResult, *msi.RunShellCommandResult, error) {
	if ts.inst == nil {
		return nil, nil, errors.New("instance not registered")
	}
	guestPath, err := ts.TranslateHostPath(args.Directory)
	if err != nil {
		return nil, nil, err
	}
	cmd := exec.CommandContext(ctx, ts.limactl,
		append([]string{"shell", "--workdir=" + guestPath, ts.inst.Name},
			args.Command...)...)
	var stdout, stderr bytes.Buffer
	cmd.Stdout = &stdout
	cmd.Stderr = &stderr
	cmdErr := cmd.Run()
	res := &msi.RunShellCommandResult{
		Stdout: stdout.String(),
		Stderr: stderr.String(),
	}
	if cmdErr == nil {
		res.ExitCode = new(0)

View on GitHub (pinned to dd909d0973)

Solutions

1. Start the MCP server attached to a running instance (limactl mcp <instance>).
2. Confirm the instance is Running with `limactl list` and restart it if stopped.
3. When embedding, call and error-check RegisterInstance before any tool call.

if ts.inst == nil {
    return errors.New("RunShellCommand requires a registered running instance")
}

func (ts *ToolSet) HasInstance() bool { return ts.inst != nil }

res, result, err := ts.RunShellCommand(ctx, req, params)
if err != nil {
    if err.Error() == "instance not registered" {
        return nil, fmt.Errorf("no instance bound; relaunch MCP server with limactl mcp <instance>")
    }
    return nil, err
}

When it happens

Trigger: Invoking the MCP RunShellCommand tool (msi.RunShellCommandParams) on a ToolSet whose RegisterInstance was never called or failed — e.g. limactl mcp without an instance target. Listed as called by SearchFileContent, whose guest-execution path shares this guard.

Common situations: An MCP agent tries to run guest shell commands right after server start with no instance selected; the target instance is stopped so registration was rejected earlier; embedded usage of the toolset skipping registration.

Related errors

• instance not registered
• field `user.shell` must be one of %v for Windows guest, got
• field `user.shell` must be an absolute path, got %#q
• expected status of instance %#q to be %#q, got %#q
• invalid value for static parameter: %#q

AI-assisted analysis of lima-vm/lima@dd909d0973 (2026-09-01). Data as JSON: /api/errors/aef9688d1742280e. Report an issue: GitHub.