golang/go · error

no engine configured

Error message

no engine configured

What it means

Returned by the script Help command when s.engine is nil. Help needs the Engine to enumerate registered commands and conditions and print their usage, so running it on a State that was not initialized through an Engine (or whose engine reference was not set) is rejected. It indicates the script environment was wired up incorrectly rather than a user script typo.

Source

Thrown at src/cmd/internal/script/cmds.go:733

		s.Logf("matched: %s\n", lines)
	}
	return nil
}

// Help writes command documentation to the script log.
func Help() Cmd {
	return Command(
		CmdUsage{
			Summary: "log help text for commands and conditions",
			Args:    "[-v] name...",
			Detail: []string{
				"To display help for a specific condition, enclose it in brackets: 'help [amd64]'.",
				"To display complete documentation when listing all commands, pass the -v flag.",
			},
		},
		func(s *State, args ...string) (WaitFunc, error) {
			if s.engine == nil {
				return nil, errors.New("no engine configured")
			}

			verbose := false
			if len(args) > 0 {
				verbose = true
				if args[0] == "-v" {
					args = args[1:]
				}
			}

			var cmds, conds []string
			for _, arg := range args {
				if strings.HasPrefix(arg, "[") && strings.HasSuffix(arg, "]") {
					conds = append(conds, arg[1:len(arg)-1])
				} else {
					cmds = append(cmds, arg)
				}
			}

View on GitHub (pinned to b6b368adc5)

Solutions

1. Run scripts through an Engine: construct Engine{Cmds:..., Conds:...} and call engine.Run(scripttest.TestMain(...)) so State.engine is populated.
2. If you must use a bare State, set s.engine to your Engine before invoking Help, or skip registering Help.
3. Replace the built-in Help with a custom command that does not require the engine, if you only need static help text.

Example fix

// before: manual State, Help fails
st := &script.State{}
st.Run(impls, []string{"help"}) // -> "no engine configured"

// after: drive through an Engine
eng := &script.Engine{Cmds: script.DefaultCmds(), Conds: script.DefaultConds()}
eng.Run(st, "help")

// Ensure an Engine is attached to the State before running scripts.
func ensureEngine(st *script.State, eng *script.Engine) {
    if st.Engine == nil { // set the field if exposed; otherwise construct via Engine.Run
        st.Engine = eng
    }
}

func isNoEngine(err error) bool {
    return err != nil && err.Error() == "no engine configured"
}

// Avoid the path entirely: run scripts through Engine.Run so State.engine is set.

When it happens

Trigger: Calling the Help command in a script run against a State that has no Engine attached — e.g. a State constructed manually for a test, or a custom Cmd injected without going through Engine.Params/Run. Help unconditionally dereferences s.engine and refuses first if it is nil.

Common situations: Writing a custom script-test harness that builds its own State instead of using Engine.Run, then exercising the built-in Help command. Registering Help in a Cmds map but forgetting to construct it through an Engine.

Related errors

• unknown command
• command cannot be run in background
• destination is not a directory
• duplicated '!' or '?' token
• empty condition

AI-assisted analysis of golang/go@b6b368adc5 (2026-08-12). Data as JSON: /api/errors/1a220e7b5a7a34aa. Report an issue: GitHub.