{"record":{"id":"aef9688d1742280e","repo":"lima-vm/lima","slug":"instance-not-registered-aef968","errorCode":null,"errorMessage":"instance not registered","messagePattern":"instance not registered","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/mcp/toolset/shell.go","lineNumber":21,"sourceCode":"\npackage toolset\n\nimport (\n\t\"bytes\"\n\t\"context\"\n\t\"errors\"\n\t\"os/exec\"\n\n\t\"github.com/modelcontextprotocol/go-sdk/mcp\"\n\n\t\"github.com/lima-vm/lima/v2/pkg/mcp/msi\"\n)\n\nfunc (ts *ToolSet) RunShellCommand(ctx context.Context,\n\t_ *mcp.CallToolRequest, args msi.RunShellCommandParams,\n) (*mcp.CallToolResult, *msi.RunShellCommandResult, error) {\n\tif ts.inst == nil {\n\t\treturn nil, nil, errors.New(\"instance not registered\")\n\t}\n\tguestPath, err := ts.TranslateHostPath(args.Directory)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tcmd := exec.CommandContext(ctx, ts.limactl,\n\t\tappend([]string{\"shell\", \"--workdir=\" + guestPath, ts.inst.Name},\n\t\t\targs.Command...)...)\n\tvar stdout, stderr bytes.Buffer\n\tcmd.Stdout = &stdout\n\tcmd.Stderr = &stderr\n\tcmdErr := cmd.Run()\n\tres := &msi.RunShellCommandResult{\n\t\tStdout: stdout.String(),\n\t\tStderr: stderr.String(),\n\t}\n\tif cmdErr == nil {\n\t\tres.ExitCode = new(0)","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/mcp/toolset/shell.go#L3-L39","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the MCP server attached to a running instance (limactl mcp <instance>).","Confirm the instance is Running with `limactl list` and restart it if stopped.","When embedding, call and error-check RegisterInstance before any tool call."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"if ts.inst == nil {\n    return errors.New(\"RunShellCommand requires a registered running instance\")\n}","typeGuard":"func (ts *ToolSet) HasInstance() bool { return ts.inst != nil }","tryCatchPattern":"res, result, err := ts.RunShellCommand(ctx, req, params)\nif err != nil {\n    if err.Error() == \"instance not registered\" {\n        return nil, fmt.Errorf(\"no instance bound; relaunch MCP server with limactl mcp <instance>\")\n    }\n    return nil, err\n}","preventionTips":["Always start the MCP server bound to a running instance.","Handle instance stop/crash by re-registering before further tool calls.","Check RegisterInstance error return in embedded integrations."],"tags":["lima","mcp","toolset","shell","instance-registration"],"backgroundTag":"instance-not-registered","analyzedSha":"dd909d0973cd84fa35f9e1693181b4585ea616c1","analyzedAt":"2026-09-01T14:24:59.842Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}