wavetermdev/waveterm · error

failed to run tsunami app: %w

Error message

failed to run tsunami app: %w

What it means

Wave failed to launch a tsunami app binary after it was downloaded and verified executable. runTsunamiAppBinary returned an error while creating pipes or starting the process, and Start wraps it with this message. It is a wrapper error — the underlying cause is in the wrapped %w chain.

Source

Thrown at pkg/blockcontroller/tsunamicontroller.go:209

			return fmt.Errorf("failed to build tsunami app: %w", err)
		}
	}

	info, err := os.Stat(cachePath)
	if err != nil {
		if os.IsNotExist(err) {
			return fmt.Errorf("app cache does not exist: %s", cachePath)
		}
		return fmt.Errorf("failed to stat app cache: %w", err)
	}

	if runtime.GOOS != "windows" && info.Mode()&0111 == 0 {
		return fmt.Errorf("app cache is not executable: %s", cachePath)
	}

	tsunamiProc, err := runTsunamiAppBinary(ctx, cachePath, appPath, blockMeta)
	if err != nil {
		return fmt.Errorf("failed to run tsunami app: %w", err)
	}

	c.tsunamiProc = tsunamiProc
	c.WithStatusLock(func() {
		c.status = Status_Running
		c.port = tsunamiProc.Port
	})
	go c.sendStatusUpdate()

	// Monitor process completion
	go func() {
		<-tsunamiProc.WaitCh
		c.runLock.Lock()
		if c.tsunamiProc == tsunamiProc {
			c.tsunamiProc = nil
			c.WithStatusLock(func() {
				c.status = Status_Done
				c.port = 0

View on GitHub (pinned to a4447c1563)

Solutions

1. Inspect the wrapped %w cause for the actual failure
2. Delete the app cache directory and re-download the app
3. Verify the binary matches the current OS/arch and is a valid ELF/Mach-O executable
4. Check ulimit/file-descriptor limits and free disk space

Example fix

// before
tsunamiProc, err := runTsunamiAppBinary(ctx, cachePath, appPath, blockMeta)
// after
if _, statErr := os.Stat(cachePath); statErr != nil {
	// force re-download of the app cache before running
}

info, err := os.Stat(cachePath)
if err != nil || info.Mode()&0111 == 0 { /* re-download app cache */ }

proc, err := ctl.Start(ctx)
if err != nil && strings.Contains(err.Error(), "failed to run tsunami app") {
	// inspect %w cause, purge cache, retry once
}

When it happens

Trigger: Starting a tsunami block when cmd.Start() fails (binary invalid, missing shared libs, wrong arch), or stdout/stderr/stdin pipe creation fails inside runTsunamiAppBinary.

Common situations: Corrupted or incompatible cached binary (e.g. macOS binary on Linux, x86 on ARM), disk or fd exhaustion, app cache partially downloaded.

Related errors

• HTTP ${response.status}: ${response.statusText}
• terminal input request failed: ${response.status} ${response
• procinfo: process not found
• failed to decode tsunami response: %w
• failed to marshal input: %w

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