{"record":{"id":"c4aa4a41e246fd46","repo":"wavetermdev/waveterm","slug":"error-creating-client-w","errorCode":null,"errorMessage":"error creating client: %w","messagePattern":"error creating client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/wcore/wcore.go","lineNumber":41,"sourceCode":"\t\"github.com/wavetermdev/waveterm/pkg/wcloud\"\n\t\"github.com/wavetermdev/waveterm/pkg/wps\"\n\t\"github.com/wavetermdev/waveterm/pkg/wstore\"\n)\n\n// the wcore package coordinates actions across the storage layer\n// orchestrating the wave object store, the wave pubsub system, and the wave rpc system\n\n// Ensures that the initial data is present in the store, creates an initial window if needed\nfunc EnsureInitialData() (bool, error) {\n\t// does not need to run in a transaction since it is called on startup\n\tctx, cancelFn := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancelFn()\n\tclient, err := wstore.DBGetSingleton[*waveobj.Client](ctx)\n\tfirstLaunch := false\n\tif err == wstore.ErrNotFound {\n\t\tclient, err = CreateClient(ctx)\n\t\tif err != nil {\n\t\t\treturn false, fmt.Errorf(\"error creating client: %w\", err)\n\t\t}\n\t\tfirstLaunch = true\n\t}\n\tif client.TempOID == \"\" {\n\t\tlog.Println(\"client.TempOID is empty\")\n\t\tclient.TempOID = uuid.NewString()\n\t\terr = wstore.DBUpdate(ctx, client)\n\t\tif err != nil {\n\t\t\treturn firstLaunch, fmt.Errorf(\"error updating client: %w\", err)\n\t\t}\n\t}\n\tif client.InstallId == \"\" {\n\t\tlog.Println(\"client.InstallId is empty\")\n\t\tclient.InstallId = uuid.NewString()\n\t\terr = wstore.DBUpdate(ctx, client)\n\t\tif err != nil {\n\t\t\treturn firstLaunch, fmt.Errorf(\"error updating client: %w\", err)\n\t\t}","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/wcore/wcore.go#L23-L59","documentation":"EnsureInitialData looks up the Client singleton; when it returns wstore.ErrNotFound, the code creates the client. This error wraps any failure of CreateClient itself — meaning first-launch client initialization could not be persisted.","triggerScenarios":"wstore.DBGetSingleton returns ErrNotFound (first launch) and the subsequent CreateClient call fails: DB write error, disk full/permissions, or another non-NotFound DB failure inside CreateClient.","commonSituations":"First run on a machine with a read-only or full data directory; corrupted store preventing singleton creation; crash mid-initialization leaving partial data.","solutions":["Inspect the wrapped error from CreateClient for the storage-level cause","Check write permissions and free space in the wave data directory (~/.waveterm)","Delete/restore a corrupted wave store so a clean first launch can recreate the client","Ensure only one instance initializes the store concurrently (lock contention can fail creation)"],"exampleFix":"// before\nif err == wstore.ErrNotFound {\n    client, err = wcore.CreateClient(ctx)\n    if err != nil { return false, fmt.Errorf(\"error creating client: %w\", err) }\n}\n// after\nif err == wstore.ErrNotFound {\n    if err := ensureStoreWritable(); err != nil { return false, err }\n    client, err = wcore.CreateClient(ctx)\n    if err != nil { return false, fmt.Errorf(\"error creating client: %w\", err) }\n}","handlingStrategy":"try-catch","validationCode":"if err == wstore.ErrNotFound {\n    if fi, statErr := os.Stat(dataDir); statErr != nil || !isWritableDir(dataDir) {\n        return false, fmt.Errorf(\"wave data dir not writable: %v\", statErr)\n    }\n}","typeGuard":null,"tryCatchPattern":"_, err := wstore.DBGetSingleton[*waveobj.Client](ctx)\nif errors.Is(err, wstore.ErrNotFound) {\n    if _, cerr := wcore.CreateClient(ctx); cerr != nil {\n        if strings.Contains(cerr.Error(), \"error creating client\") {\n            // check data dir writability, disk space, single-instance lock\n        }\n    }\n}","preventionTips":["Check ~/.waveterm writability and disk space before first launch","Ensure only one app instance initializes the store","Treat this as fatal on first launch — nothing else can proceed without a client record"],"tags":["waveterm","wstore","client","first-launch","initialization"],"backgroundTag":"initialization-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}