{"record":{"id":"180846b7eeb2c630","repo":"lima-vm/lima","slug":"instance-not-registered","errorCode":null,"errorMessage":"instance not registered","messagePattern":"instance not registered","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/mcp/toolset/filesystem.go","lineNumber":84,"sourceCode":"\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tres := &msi.ReadFileResult{\n\t\tContent: string(b),\n\t}\n\treturn &mcp.CallToolResult{\n\t\t// Gemini:\n\t\t// For text files: The file content, potentially prefixed with a truncation message\n\t\t// (e.g., [File content truncated: showing lines 1-100 of 500 total lines...]\\nActual file content...).\n\t\tStructuredContent: res,\n\t}, res, nil\n}\n\nfunc (ts *ToolSet) WriteFile(_ context.Context,\n\t_ *mcp.CallToolRequest, args msi.WriteFileParams,\n) (*mcp.CallToolResult, *msi.WriteFileResult, error) {\n\tif ts.inst == nil {\n\t\treturn nil, nil, errors.New(\"instance not registered\")\n\t}\n\tguestPath, err := ts.TranslateHostPath(args.Path)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tdir := filepath.Dir(guestPath)\n\terr = ts.sftp.MkdirAll(dir)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tf, err := ts.sftp.Create(guestPath)\n\tif err != nil {\n\t\treturn nil, nil, err\n\t}\n\tdefer f.Close()\n\t_, err = f.Write([]byte(args.Content))\n\tif err != nil {\n\t\treturn nil, nil, err","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/lima-vm/lima/blob/dd909d0973cd84fa35f9e1693181b4585ea616c1/pkg/mcp/toolset/filesystem.go#L66-L102","documentation":"The MCP filesystem ToolSet's WriteFile tool returns this error when ToolSet.inst is nil, i.e. no Lima instance has been registered via ToolSet.RegisterInstance. WriteFile needs the registered instance to translate guest paths and open an SFTP connection to the VM; without registration it cannot proceed and fails fast with a sentinel error.","triggerScenarios":"Calling the MCP tool msi.WriteFile (guest file write) on a ToolSet where RegisterInstance was never called, was never invoked by the limactl mcp server startup, or the server was started without an instance argument.","commonSituations":"Starting the MCP server (limactl mcp) without specifying/starting a running instance; the MCP client connecting before an instance is selected; tests or embeddings of pkg/mcp/toolset that skip RegisterInstance.","solutions":["Start the MCP server bound to a running instance (limactl mcp <instance>) so RegisterInstance runs.","Ensure the instance is running first (limactl start <instance>), since RegisterInstance rejects non-running instances.","In code, call ts.RegisterInstance(ctx, inst) with a loaded *limatype.Instance before invoking WriteFile."],"exampleFix":"// before\nts := toolset.NewToolSet(limactlPath)\nserver := mcp.NewServer(...)\nts.RegisterServer(server) // inst == nil\n// after\nts := toolset.NewToolSet(limactlPath)\ninst, _ := store.Inspect(ctx, instName)\nif err := ts.RegisterInstance(ctx, inst); err != nil { return err }\nts.RegisterServer(server)","handlingStrategy":"try-catch","validationCode":"if ts.InstaceNotRegistered() { // inst == nil check before invoking tool\n    return errors.New(\"register a running instance first: limactl mcp <instance>\")\n}","typeGuard":"func (ts *ToolSet) HasInstance() bool { return ts.inst != nil }","tryCatchPattern":"res, result, err := ts.WriteFile(ctx, req, params)\nif err != nil {\n    if err.Error() == \"instance not registered\" {\n        return nil, fmt.Errorf(\"no Lima instance bound to MCP server; restart with limactl mcp <instance>\")\n    }\n    return nil, err\n}","preventionTips":["Always launch the limactl MCP server with an instance argument.","Call RegisterInstance during server init and abort startup if it errors.","Check instance status is Running before binding it to the toolset."],"tags":["lima","mcp","toolset","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"}