wavetermdev/waveterm · error

error creating blockfile: %w

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.

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)

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: %w
• failed to create WaveFS file: %w
• error making blockfile %q: %w
• error statting term file: %w
• error reading term file: %w

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