wavetermdev/waveterm · error

failed to read app manifest: %w

Error message

failed to read app manifest: %w

What it means

runBuilderApp starts by reading the app's manifest via waveappstore.ReadAppManifest(appId); this wrapped error indicates the manifest could not be read or parsed, so the process cannot be configured and launched. The build succeeded, but the app metadata layer is broken.

Source

Thrown at pkg/buildercontroller/buildercontroller.go:307

		}
	}

	go func() {
		<-process.WaitCh
		bc.lock.Lock()
		if bc.process == process {
			bc.process = nil
			exitCode := exitCodeFromWaitErr(process.WaitRtn)
			bc.setStatus_nolock(BuilderStatus_Stopped, 0, exitCode, "")
		}
		bc.lock.Unlock()
	}()
}

func (bc *BuilderController) runBuilderApp(ctx context.Context, appId string, appBinPath string, builderEnv map[string]string) (*BuilderProcess, error) {
	manifest, err := waveappstore.ReadAppManifest(appId)
	if err != nil {
		return nil, fmt.Errorf("failed to read app manifest: %w", err)
	}

	secretBindings, err := waveappstore.ReadAppSecretBindings(appId)
	if err != nil {
		return nil, fmt.Errorf("failed to read secret bindings (ERR-SECRET): %w", err)
	}

	secretEnv, err := waveappstore.BuildAppSecretEnv(appId, manifest, secretBindings)
	if err != nil {
		return nil, fmt.Errorf("failed to build secret environment (ERR-SECRET): %w", err)
	}

	if builderEnv == nil {
		builderEnv = make(map[string]string)
	}
	for k, v := range secretEnv {
		builderEnv[k] = v
	}

View on GitHub (pinned to a4447c1563)

Solutions

1. Check the manifest file exists in the app dir and re-create/reinstall the app if missing
2. Validate manifest JSON syntax and required fields
3. Compare manifest schema against the current waveappstore expectations after upgrades
4. Fix file permissions on the app directory

Example fix

// before
// app dir has binary but manifest deleted by cleanup script
// after
// reinstall app or restore app.json before runBuilderApp

if _, err := waveappstore.ReadAppManifest(appId); err != nil {
    return fmt.Errorf("manifest invalid, reinstall app: %w", err)
}

if err := runApp(appId); err != nil {
    if strings.Contains(err.Error(), "failed to read app manifest") { /* trigger reinstall */ }
}

When it happens

Trigger: ReadAppManifest fails — manifest file missing from the app dir, malformed JSON, or read permission denied.

Common situations: App directory partially deleted (binary kept, manifest removed); manual edits corrupting app.json; a version upgrade changing manifest schema; restrictive file permissions after restore from backup.

Related errors

• failed to get app directory: %w
• failed to get builder executable path: %w
• build output not found: %w
• failed to stat file for backup: %w
• failed to read file for backup: %w

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