wavetermdev/waveterm · error

error creating starter workspace: %w

Error message

error creating starter workspace: %w

What it means

Returned when creation of the starter (default) workspace fails during initialization, e.g. a persistence or configuration error. The underlying error is wrapped with %w.

Source

Thrown at pkg/wcore/wcore.go:77

		}
	}
	log.Printf("clientid: %s\n", client.OID)
	wstore.SetClientId(client.OID)
	if len(client.WindowIds) == 1 {
		log.Println("client has one window")
		CheckAndFixWindow(ctx, client.WindowIds[0])
		return firstLaunch, nil
	}
	if len(client.WindowIds) > 0 {
		log.Println("client has windows")
		return firstLaunch, nil
	}
	wsId := ""
	if firstLaunch {
		log.Println("client has no windows and first launch, creating starter workspace")
		starterWs, err := CreateWorkspace(ctx, "Starter workspace", "custom@wave-logo-solid", "#58C142", false, true)
		if err != nil {
			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)

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the wrapped error for the root cause (insert vs validation failure)
2. Verify the wavetool DB is writable and not corrupted
3. Delete the DB to force clean first-launch initialization
4. Report a bug with logs if the starter workspace fails on a fresh install

clientData, err := wcore.GetClientData(ctx)
isFirstLaunch := err == nil && len(clientData.WindowIds) == 0
if isFirstLaunch { /* verify DB writable before CreateWorkspace */ }

firstLaunch, err := wcore.EnsureInitialData(ctx)
if err != nil && strings.Contains(err.Error(), "starter workspace") {
    log.Printf("starter workspace creation failed: %v", err)
}

When it happens

Trigger: firstLaunch is true (client has no windows) and CreateWorkspace(ctx, "Starter workspace", ...) returns an error — typically the underlying wstore.DBInsert of the new workspace object fails.

Common situations: First run with a failing/unwritable DB; a partially initialized workspace table; schema migration problems after upgrading Wave.

Related errors

• error getting workspace: %w
• error getting tab: %w
• error getting tab blocks: %w
• error creating window: %w
• error updating window: %w

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