lima-vm/lima · error

instance not registered

Error message

instance not registered

What it means

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.

Source

Thrown at pkg/mcp/toolset/filesystem.go:84

	if err != nil {
		return nil, nil, err
	}
	res := &msi.ReadFileResult{
		Content: string(b),
	}
	return &mcp.CallToolResult{
		// Gemini:
		// For text files: The file content, potentially prefixed with a truncation message
		// (e.g., [File content truncated: showing lines 1-100 of 500 total lines...]\nActual file content...).
		StructuredContent: res,
	}, res, nil
}

func (ts *ToolSet) WriteFile(_ context.Context,
	_ *mcp.CallToolRequest, args msi.WriteFileParams,
) (*mcp.CallToolResult, *msi.WriteFileResult, error) {
	if ts.inst == nil {
		return nil, nil, errors.New("instance not registered")
	}
	guestPath, err := ts.TranslateHostPath(args.Path)
	if err != nil {
		return nil, nil, err
	}
	dir := filepath.Dir(guestPath)
	err = ts.sftp.MkdirAll(dir)
	if err != nil {
		return nil, nil, err
	}
	f, err := ts.sftp.Create(guestPath)
	if err != nil {
		return nil, nil, err
	}
	defer f.Close()
	_, err = f.Write([]byte(args.Content))
	if err != nil {
		return nil, nil, err

View on GitHub (pinned to dd909d0973)

Solutions

1. Start the MCP server bound to a running instance (limactl mcp <instance>) so RegisterInstance runs.
2. Ensure the instance is running first (limactl start <instance>), since RegisterInstance rejects non-running instances.
3. In code, call ts.RegisterInstance(ctx, inst) with a loaded *limatype.Instance before invoking WriteFile.

Example fix

// before
ts := toolset.NewToolSet(limactlPath)
server := mcp.NewServer(...)
ts.RegisterServer(server) // inst == nil
// after
ts := toolset.NewToolSet(limactlPath)
inst, _ := store.Inspect(ctx, instName)
if err := ts.RegisterInstance(ctx, inst); err != nil { return err }
ts.RegisterServer(server)

if ts.InstaceNotRegistered() { // inst == nil check before invoking tool
    return errors.New("register a running instance first: limactl mcp <instance>")
}

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

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• instance not registered
• expected status of instance %#q to be %#q, got %#q
• invalid value for static parameter: %#q
• invalid parameter %#q, expected `static=` followed by a bool
• invalid parameter %#q, expected NAME=VALUE

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