wavetermdev/waveterm · error

error creating blockfile

Error message

error creating blockfile: %w

What it means

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.

Solutions

1. Check free disk space and file permissions in the Wave data directory (~/.waveterm)
2. Retry the command — transient storage/timeout failures may clear; the 2s timeout can expire under load
3. If the blockfile is stuck in a bad state, close/reopen the block (fs.ErrExist path resets terminal state; other errors do not)
4. Inspect/repair the wave filestore (waveshell data dir) or reset it if corrupted, then restart Wave

Example fix

// before: ignoring storage health
bc.setupAndStartShellProcess(logCtx, rc, blockMeta)

// after: check writable data dir first
if err := wavebase.EnsureDataDir(); err != nil {
    return fmt.Errorf("check ~/.waveterm writable & disk space: %w", err)
}
bc.setupAndStartShellProcess(logCtx, rc, blockMeta)

// precheck: data dir writable and disk has headroom
if err := wavebase.EnsureDataDir(); err != nil {
    return fmt.Errorf("wave data dir not writable: %w", err)
}

proc, err := bc.setupAndStartShellProcess(logCtx, rc, blockMeta)
if err != nil && strings.Contains(err.Error(), "error creating blockfile") {
    // check disk space/permissions; optionally reset terminal state and retry once
}

When it happens

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

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

Related errors

• error creating block term file
• error making blockfile
• error reading term file
• error statting term file
• failed to create WaveFS file

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

Appendix: source

Thrown at pkg/blockcontroller/shellcontroller.go:383

		}
		rtn.ConnType = ConnType_Ssh
		rtn.SshConn = conn
		rtn.WshEnabled = wshEnabled && conn.WshEnabled.Load()
	}
	err := rtn.getRemoteInfoAndShellType(blockMeta)
	if err != nil {
		return ConnUnion{}, err
	}
	return rtn, nil
}

func (bc *ShellController) setupAndStartShellProcess(logCtx context.Context, rc *RunShellOpts, blockMeta waveobj.MetaMapType) (*shellexec.ShellProc, error) {
	// create a circular blockfile for the output
	ctx, cancelFn := context.WithTimeout(context.Background(), 2*time.Second)
	defer cancelFn()
	fsErr := filestore.WFS.MakeFile(ctx, bc.BlockId, wavebase.BlockFile_Term, nil, wshrpc.FileOpts{MaxSize: DefaultTermMaxFileSize, Circular: true})
	if fsErr != nil && fsErr != fs.ErrExist {
		return nil, fmt.Errorf("error creating blockfile: %w", fsErr)
	}
	if fsErr == fs.ErrExist {
		// reset the terminal state
		bc.resetTerminalState(logCtx)
	}
	bcInitStatus := bc.GetRuntimeStatus()
	if bcInitStatus.ShellProcStatus == Status_Running {
		return nil, nil
	}
	// TODO better sync here (don't let two starts happen at the same times)
	remoteName := blockMeta.GetString(waveobj.MetaKey_Connection, "")
	connUnion, err := bc.getConnUnion(logCtx, remoteName, blockMeta)
	if err != nil {
		return nil, err
	}
	blocklogger.Infof(logCtx, "[conndebug] remoteName: %q, connType: %s, wshEnabled: %v, shell: %q, shellType: %s\n", remoteName, connUnion.ConnType, connUnion.WshEnabled, connUnion.ShellPath, connUnion.ShellType)
	var cmdStr string
	var cmdOpts shellexec.CommandOptsType

View on GitHub (pinned to a4447c1563)