wavetermdev/waveterm · error

failed to start process: %w

Error message

failed to start process: %w

What it means

After configuring the builder subprocess command, runBuilderApp calls cmd.Start(). This error wraps any failure to spawn the process — most commonly the builder binary does not exist at the configured path, lacks execute permission, or the working directory set on the Cmd does not exist.

Source

Thrown at pkg/buildercontroller/buildercontroller.go:368

		return nil, fmt.Errorf("failed to create stdin pipe: %w", err)
	}

	portChan := make(chan int, 1)
	portFound := false

	bc.outputBuffer.SetLineCallback(func(line string) {
		if !portFound {
			if port := build.ParseTsunamiPort(line); port > 0 {
				portFound = true
				portChan <- port
			}
		}
		bc.publishOutputLine(line, false)
	})

	err = cmd.Start()
	if err != nil {
		return nil, fmt.Errorf("failed to start process: %w", err)
	}

	waitCh := make(chan struct{})
	process := &BuilderProcess{
		Cmd:         cmd,
		StdinWriter: stdinPipe,
		WaitCh:      waitCh,
	}

	go func() {
		process.WaitRtn = cmd.Wait()
		close(waitCh)
	}()

	go bc.outputBuffer.ReadAll(stdoutPipe)
	go bc.outputBuffer.ReadAll(stderrPipe)

	errChan := make(chan error, 1)

View on GitHub (pinned to a4447c1563)

Solutions

1. Verify the builder binary exists and is executable at the resolved path (run 'make build' if missing)
2. Check the wrapped error: 'no such file or directory' means wrong path; 'permission denied' means chmod +x
3. Ensure the Cmd's Dir (working directory) exists before Start()
4. Check disk space and container fd/process limits if fork/exec fails

Example fix

// before
err = cmd.Start()
// after
if _, err := os.Stat(builderPath); err != nil {
    return nil, fmt.Errorf("builder binary missing at %s (run make build): %w", builderPath, err)
}
err = cmd.Start()
if err != nil { return nil, fmt.Errorf("failed to start process: %w", err) }

if _, err := os.Stat(builderBinaryPath); err != nil {
    return fmt.Errorf("builder binary not available: %w", err)
}
if info, err := os.Stat(builderBinaryPath); err == nil && info.Mode()&0o111 == 0 {
    return fmt.Errorf("builder binary is not executable")
}

process, err := bc.runBuilderApp(ctx, ...)
if err != nil && strings.Contains(err.Error(), "failed to start process") {
    // hint: run 'make build' if the wrapped error is 'no such file or directory'
    return err
}

When it happens

Trigger: cmd.Start() fails: builder executable not found (ErrNotFound), not executable (permission denied), configured Dir missing, or fork/exec failure.

Common situations: Wave built from source without 'make build' (waveshell binary absent); PATH not carrying the build output dir; antivirus/permission issues; bad working directory in block context.

Related errors

• failed to create stdout pipe: %w
• failed to create stderr pipe: %w
• failed to create stdin pipe: %w
• process died before emitting port
• timeout waiting for port

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