wavetermdev/waveterm · error

%s environment variable must be set

Error message

%s environment variable must be set

What it means

The tsunami build tool requires the EnvTsunamiScaffoldPath environment variable to point at the scaffold module used to generate new tsunami apps. validateEnvironmentVars aborts the build early if it is unset or empty.

Source

Thrown at tsunami/cmd/main-tsunami.go:42

var rootCmd = &cobra.Command{
	Use:   "tsunami",
	Short: "Tsunami - A VDOM-based UI framework",
	Long:  `Tsunami is a VDOM-based UI framework for building modern applications.`,
}

var versionCmd = &cobra.Command{
	Use:   "version",
	Short: "Print Tsunami version",
	Long:  `Print Tsunami version`,
	Run: func(cmd *cobra.Command, args []string) {
		fmt.Println("v" + tsunamibase.TsunamiVersion)
	},
}

func validateEnvironmentVars(opts *build.BuildOpts) error {
	scaffoldPath := os.Getenv(EnvTsunamiScaffoldPath)
	if scaffoldPath == "" {
		return fmt.Errorf("%s environment variable must be set", EnvTsunamiScaffoldPath)
	}
	absScaffoldPath, err := filepath.Abs(scaffoldPath)
	if err != nil {
		return fmt.Errorf("failed to resolve %s to absolute path: %w", EnvTsunamiScaffoldPath, err)
	}

	sdkReplacePath := os.Getenv(EnvTsunamiSdkReplacePath)
	if sdkReplacePath == "" {
		return fmt.Errorf("%s environment variable must be set", EnvTsunamiSdkReplacePath)
	}
	absSdkReplacePath, err := filepath.Abs(sdkReplacePath)
	if err != nil {
		return fmt.Errorf("failed to resolve %s to absolute path: %w", EnvTsunamiSdkReplacePath, err)
	}

	opts.ScaffoldPath = absScaffoldPath
	opts.SdkReplacePath = absSdkReplacePath

View on GitHub (pinned to a4447c1563)

Solutions

1. Export EnvTsunamiScaffoldPath (see its constant value, e.g. export TSUNAMI_SCAFFOLD_PATH=/path/to/scaffold) before running the command
2. Set it in CI configuration/secrets for the pipeline
3. Add it to your shell profile so it persists

Example fix

// before
$ tsunami build ./myapp
// after
$ export TSUNAMI_SCAFFOLD_PATH=$HOME/go/src/github.com/org/tsunami-scaffold
$ tsunami build ./myapp

if os.Getenv("TSUNAMI_SCAFFOLD_PATH") == "" {
    return errors.New("TSUNAMI_SCAFFOLD_PATH must be set")
}

if err := validateEnvironmentVars(opts); err != nil {
    log.Fatalf("env validation failed: %v", err)
}

When it happens

Trigger: Running main-tsunami (build entrypoint) without TSUNAMI_SCAFFOLD_PATH exported in the environment.

Common situations: Running the CLI in a fresh shell/CI job where the env var was never set; invoking the tool from an IDE that does not inherit your shell env; typos in the variable name in your profile.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• failed to resolve %s to absolute path: %w
• wcloud endpoint not set
• wcloud ping endpoint not set
• setting auth key: %v
• --conn parameter is required

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