wavetermdev/waveterm · error

failed to create WaveFS file: %w

Error message

failed to create WaveFS file: %w

What it means

StartJob creates the job's circular output capture file (JobOutputFileName, 10MB max) in WaveFS via filestore.WFS.MakeFile; failure is wrapped with this message. The WaveFS file for a job lives under the job's OID in the virtual file store, so this signals virtual-filesystem or underlying storage failure.

Source

Thrown at pkg/jobcontroller/jobcontroller.go:689

		err = AttachJobToBlock(ctx, jobId, params.BlockId)
		if err != nil {
			return "", fmt.Errorf("failed to attach job to block: %w", err)
		}
	}
	bareRpc := wshclient.GetBareRpcClient()
	broker := bareRpc.StreamBroker
	readerRouteId := wshclient.GetBareRpcClientRouteId()
	writerRouteId := wshutil.MakeJobRouteId(jobId)
	reader, streamMeta := broker.CreateStreamReader(readerRouteId, writerRouteId, DefaultStreamRwnd)
	jobStreamIds.Set(jobId, streamMeta.Id)

	fileOpts := wshrpc.FileOpts{
		MaxSize:  10 * 1024 * 1024,
		Circular: true,
	}
	err = filestore.WFS.MakeFile(ctx, jobId, JobOutputFileName, wshrpc.FileMeta{}, fileOpts)
	if err != nil {
		return "", fmt.Errorf("failed to create WaveFS file: %w", err)
	}

	clientId := wstore.GetClientId()
	publicKey := wavejwt.GetPublicKey()
	publicKeyBase64 := base64.StdEncoding.EncodeToString(publicKey)
	jobEnv := envutil.CopyAndAddToEnvMap(params.Env, "WAVETERM_JOBID", jobId)
	startJobData := wshrpc.CommandRemoteStartJobData{
		Cmd:                params.Cmd,
		Args:               params.Args,
		Env:                jobEnv,
		TermSize:           *params.TermSize,
		StreamMeta:         streamMeta,
		JobAuthToken:       jobAuthToken,
		JobId:              jobId,
		MainServerJwtToken: jobAccessToken,
		ClientId:           clientId,
		PublicKeyBase64:    publicKeyBase64,
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Read the wrapped cause (%w): if it is 'file already exists', delete or recreate the job output file and retry with a new job.
2. Check disk space and write permissions in the Wave data directory.
3. Retry StartJob — a fresh jobId creates a fresh WaveFS path.

jobId, err := jobcontroller.StartJob(ctx, params)
if err != nil && strings.Contains(err.Error(), "failed to create WaveFS file") {
    // retry: a new jobId creates a fresh WaveFS path
    jobId, err = jobcontroller.StartJob(ctx, params)
}

When it happens

Trigger: MakeFile errors because the job's WaveFS directory/file cannot be created — e.g. a file with the same name already exists with incompatible opts, underlying blockfile/storage I/O error, or the job record insert left partial state.

Common situations: Retrying StartJob after a partial failure left a stale output file, disk full, storage backend (local file system) permission problems.

Related errors

• error creating blockfile: %w
• accessing file %s: %w
• getting absolute path for %s: %w
• reading directory %s: %w
• reading file %s: %w

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