wavetermdev/waveterm · error

failed to check local app: %w

Error message

failed to check local app: %w

What it means

While checking whether the app exists, RenameLocalApp stats the old local directory. If os.Stat fails with an error other than NotExist (permission denied, I/O error, path issues), the function aborts with "failed to check local app: %w". This distinguishes real filesystem failures from a simply-missing app.

Source

Thrown at pkg/waveappstore/waveappstore.go:673

	if err := ValidateAppId(newLocalAppId); err != nil {
		return fmt.Errorf("invalid new app name: %w", err)
	}

	homeDir := wavebase.GetHomeDir()
	waveappsDir := filepath.Join(homeDir, "waveapps")

	oldLocalDir := filepath.Join(waveappsDir, AppNSLocal, appName)
	newLocalDir := filepath.Join(waveappsDir, AppNSLocal, newAppName)
	oldDraftDir := filepath.Join(waveappsDir, AppNSDraft, appName)
	newDraftDir := filepath.Join(waveappsDir, AppNSDraft, newAppName)

	// Check if at least one of the apps exists
	localExists := false
	draftExists := false
	if _, err := os.Stat(oldLocalDir); err == nil {
		localExists = true
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("failed to check local app: %w", err)
	}

	if _, err := os.Stat(oldDraftDir); err == nil {
		draftExists = true
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("failed to check draft app: %w", err)
	}

	if !localExists && !draftExists {
		return fmt.Errorf("app '%s' does not exist in local or draft namespace", appName)
	}

	// Check if new app name already exists in either namespace
	if _, err := os.Stat(newLocalDir); err == nil {
		return fmt.Errorf("local app '%s' already exists", newAppName)
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("failed to check if new local app exists: %w", err)
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Check permissions on ~/waveapps (and the app's local/ subdirectory) and fix with chmod/chown
2. Verify the volume containing the home directory is mounted and healthy
3. Run the process as the user who owns the waveapps directory

// pre-check access to the waveapps tree
if err := os.Access(filepath.Join(wavebase.GetHomeDir(), "waveapps", "local"), os.R_OK); err != nil {
    return fmt.Errorf("no read access to local apps dir: %w", err)
}

if err := waveappstore.RenameLocalApp(oldName, newName); err != nil {
    var pe *fs.PathError
    if strings.Contains(err.Error(), "failed to check local app") && errors.As(err, &pe) {
        return fmt.Errorf("filesystem problem on %s: %w", pe.Path, pe.Err)
    }
    return err
}

When it happens

Trigger: os.Stat(oldLocalDir) returns a non-ENOENT error: the waveapps directory or its parents are unreadable, permissions deny access, or an I/O error occurs during the stat.

Common situations: Restrictive file permissions on ~/waveapps, the home directory moved or is on a failing/unmounted volume, running as a different user without access to the app directory.

Related errors

• failed to check draft app: %w
• failed to check if new local app exists: %w
• failed to create backup directory: %w
• failed to create socket directory: %w
• failed to create log directory: %w

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