wavetermdev/waveterm · critical

error inserting client: %w

Error message

error inserting client: %w

What it means

Returned when inserting a new client record into the client store fails, e.g. a database or ID conflict error. The underlying error is wrapped with %w.

Source

Thrown at pkg/wcore/wcore.go:95

			return firstLaunch, fmt.Errorf("error creating starter workspace: %w", err)
		}
		wsId = starterWs.OID
	}
	_, err = CreateWindow(ctx, nil, wsId)
	if err != nil {
		return firstLaunch, fmt.Errorf("error creating window: %w", err)
	}
	return firstLaunch, nil
}

func CreateClient(ctx context.Context) (*waveobj.Client, error) {
	client := &waveobj.Client{
		OID:       uuid.NewString(),
		WindowIds: []string{},
	}
	err := wstore.DBInsert(ctx, client)
	if err != nil {
		return nil, fmt.Errorf("error inserting client: %w", err)
	}
	return client, nil
}

func GetClientData(ctx context.Context) (*waveobj.Client, error) {
	clientData, err := wstore.DBGetSingleton[*waveobj.Client](ctx)
	if err != nil {
		return nil, fmt.Errorf("error getting client data: %w", err)
	}
	return clientData, nil
}

func SendWaveObjUpdate(oref waveobj.ORef) {
	ctx, cancelFn := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancelFn()
	// send a waveobj:update event
	waveObj, err := wstore.DBGetORef(ctx, oref)
	if err != nil {

View on GitHub (pinned to a4447c1563)

Solutions

1. Check the wrapped wstore error for the exact DB failure
2. Ensure the Wave data directory is writable
3. Remove a corrupted DB file to allow fresh client creation
4. Avoid running multiple Wave instances concurrently during first launch

// no client singleton should exist yet
_, err := wstore.DBGetSingleton[*waveobj.Client](ctx)
if err == nil { log.Println("client already exists; skip CreateClient") }

client, err := wcore.CreateClient(ctx)
if err != nil {
    log.Printf("client creation failed: %v", err)
    return err
}

When it happens

Trigger: wstore.DBInsert(ctx, client) returns an error while inserting the new Client singleton — DB unavailable, schema conflict, or an existing client row colliding.

Common situations: Very first launch where the client record must be created; corrupted DB containing an unexpected client row; DB write failures from permissions or disk.

Related errors

• error updating client: %w
• error getting client data: %w
• error inserting mainserver: %w
• error updating mainserver: %w
• error updating window: %w

AI-assisted analysis of wavetermdev/waveterm@a4447c1563 (2026-09-01). Data as JSON: /api/errors/c940869e3586d40b. Report an issue: GitHub.