wtfutil/wtf · error

command shell not defined in $SHELL environment variable

Error message

command shell not defined in $SHELL environment variable

What it means

The progress widget's execValueCmd runs a shell command by invoking the user's shell. It is constructed by joining the shell path (from widget.shell, sourced from $SHELL) with the command, so without a shell path the exec call cannot be built. The widget deliberately refuses to run and returns this sentinel error (errShellUndefined) instead of guessing a default shell like /bin/sh.

Source

Thrown at modules/progress/widget.go:18

package progress

import (
	"errors"
	"fmt"
	"os"
	"os/exec"
	"strconv"
	"strings"

	"github.com/charmbracelet/bubbles/progress"
	"github.com/muesli/reflow/ansi"
	"github.com/rivo/tview"
	"github.com/wtfutil/wtf/utils"
	"github.com/wtfutil/wtf/view"
)

var errShellUndefined = errors.New("command shell not defined in $SHELL environment variable")

// Widget is the container for your module's data
type Widget struct {
	view.TextWidget

	settings *Settings

	minimum float64
	maximum float64
	current float64
	percent float64

	padding string

	shell string

	err error
}

View on GitHub (pinned to bb838c1ccb)

Solutions

1. Set the SHELL environment variable before launching WTFUtil (e.g. export SHELL=/bin/bash or SHELL=/bin/zsh wtfutil).
2. If launching from systemd/cron, add Environment=SHELL=/bin/bash to the unit or crontab entry.
3. As a workaround inside the module config, check whether the progress module allows configuring the shell via settings and set it explicitly.

Example fix

// before (launch environment without SHELL)
$ wtfutil
// error: command shell not defined in $SHELL environment variable

// after
$ export SHELL=/bin/bash
$ wtfutil

if os.Getenv("SHELL") == "" {
    return errors.New("$SHELL must be set before running wtfutil progress module")
}

val, err := widget.execValueCmd(cmd)
if errors.Is(err, errShellUndefined) {
    // fall back to a default shell or skip the module
}

When it happens

Trigger: Calling widget.execValueCmd(cmd) when widget.shell is an empty string. This happens when the $SHELL environment variable is unset or empty in the environment WTFUtil was launched from (e.g. started by systemd, cron, a launcher, or an IDE that strips env).

Common situations: WTFUtil launched via a systemd user service, desktop autostart, cron job, or IDE run configuration where $SHELL is not exported; minimal containers or CI environments without $SHELL set.

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

• client was not initialized
• github client v3 failed to load
• cannot expand user-specific home dir
• error fetching tasks: %s
• azure workspace ID is required but not configured

AI-assisted analysis of wtfutil/wtf@bb838c1ccb (2026-09-03). Data as JSON: /api/errors/f05b7dbdd4df307d. Report an issue: GitHub.