{"record":{"id":"942878947e0c3b10","repo":"wavetermdev/waveterm","slug":"error-creating-blockfile-w","errorCode":null,"errorMessage":"error creating blockfile: %w","messagePattern":"error creating blockfile: %w","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/blockcontroller/shellcontroller.go","lineNumber":383,"sourceCode":"\t\t}\n\t\trtn.ConnType = ConnType_Ssh\n\t\trtn.SshConn = conn\n\t\trtn.WshEnabled = wshEnabled && conn.WshEnabled.Load()\n\t}\n\terr := rtn.getRemoteInfoAndShellType(blockMeta)\n\tif err != nil {\n\t\treturn ConnUnion{}, err\n\t}\n\treturn rtn, nil\n}\n\nfunc (bc *ShellController) setupAndStartShellProcess(logCtx context.Context, rc *RunShellOpts, blockMeta waveobj.MetaMapType) (*shellexec.ShellProc, error) {\n\t// create a circular blockfile for the output\n\tctx, cancelFn := context.WithTimeout(context.Background(), 2*time.Second)\n\tdefer cancelFn()\n\tfsErr := filestore.WFS.MakeFile(ctx, bc.BlockId, wavebase.BlockFile_Term, nil, wshrpc.FileOpts{MaxSize: DefaultTermMaxFileSize, Circular: true})\n\tif fsErr != nil && fsErr != fs.ErrExist {\n\t\treturn nil, fmt.Errorf(\"error creating blockfile: %w\", fsErr)\n\t}\n\tif fsErr == fs.ErrExist {\n\t\t// reset the terminal state\n\t\tbc.resetTerminalState(logCtx)\n\t}\n\tbcInitStatus := bc.GetRuntimeStatus()\n\tif bcInitStatus.ShellProcStatus == Status_Running {\n\t\treturn nil, nil\n\t}\n\t// TODO better sync here (don't let two starts happen at the same times)\n\tremoteName := blockMeta.GetString(waveobj.MetaKey_Connection, \"\")\n\tconnUnion, err := bc.getConnUnion(logCtx, remoteName, blockMeta)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tblocklogger.Infof(logCtx, \"[conndebug] remoteName: %q, connType: %s, wshEnabled: %v, shell: %q, shellType: %s\\n\", remoteName, connUnion.ConnType, connUnion.WshEnabled, connUnion.ShellPath, connUnion.ShellType)\n\tvar cmdStr string\n\tvar cmdOpts shellexec.CommandOptsType","sourceCodeStart":365,"sourceCodeEnd":401,"githubUrl":"https://github.com/wavetermdev/waveterm/blob/a4447c1563b2df285ab89e76c82f91e1a1a49c1e/pkg/blockcontroller/shellcontroller.go#L365-L401","documentation":"Wraps a filestore error from WFS.MakeFile when creating the circular terminal blockfile (BlockFile_Term) fails with an error other than fs.ErrExist. This file buffers block output (DefaultTermMaxFileSize, Circular), so shell startup aborts if it cannot be created.","triggerScenarios":"filestore.WFS.MakeFile returns a real error (not ErrExist) within the 2-second timeout — storage backend failure, permission problem, or timeout creating the per-block circular file.","commonSituations":"Disk full or quota exceeded on the machine hosting the Wave data directory; filesystem permissions broken after an OS update or running once as root; slow/locked storage exceeding the 2s context timeout; corrupted wave filestore database.","solutions":["Check free disk space and file permissions in the Wave data directory (~/.waveterm)","Retry the command — transient storage/timeout failures may clear; the 2s timeout can expire under load","If the blockfile is stuck in a bad state, close/reopen the block (fs.ErrExist path resets terminal state; other errors do not)","Inspect/repair the wave filestore (waveshell data dir) or reset it if corrupted, then restart Wave"],"exampleFix":"// before: ignoring storage health\nbc.setupAndStartShellProcess(logCtx, rc, blockMeta)\n\n// after: check writable data dir first\nif err := wavebase.EnsureDataDir(); err != nil {\n    return fmt.Errorf(\"check ~/.waveterm writable & disk space: %w\", err)\n}\nbc.setupAndStartShellProcess(logCtx, rc, blockMeta)","handlingStrategy":"try-catch","validationCode":"// precheck: data dir writable and disk has headroom\nif err := wavebase.EnsureDataDir(); err != nil {\n    return fmt.Errorf(\"wave data dir not writable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)\nif err != nil && strings.Contains(err.Error(), \"error creating blockfile\") {\n    // check disk space/permissions; optionally reset terminal state and retry once\n}","preventionTips":["Monitor free disk space where ~/.waveterm lives","Never run Wave as root against a user-owned data dir (permission skew)","Keep the filestore timeout in mind: avoid starting many shells simultaneously on slow storage"],"tags":["filestore","filesystem","storage"],"backgroundTag":"blockfile-creation-failed","analyzedSha":"a4447c1563b2df285ab89e76c82f91e1a1a49c1e","analyzedAt":"2026-09-01T15:26:23.972Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}