hasura/graphql-engine · warning

unknown shell: %s. Use bash or zsh

Error message

unknown shell: %s. Use bash or zsh

What it means

Simple validation error from `hasura completion`: the --shell flag (o.Shell) was neither "bash" nor "zsh", so the switch's default branch builds this error directly with fmt.Errorf. Only bash and zsh are supported for completion generation.

Source

Thrown at cli/commands/completion.go:116

		op  errors.Op = "commands.completionOptions.run"
		err error
	)

	switch o.Shell {
	case "bash":
		if o.File != "" {
			err = o.Cmd.Root().GenBashCompletionFile(o.File)
		} else {
			err = o.Cmd.Root().GenBashCompletion(os.Stdout)
		}
	case "zsh":
		if o.File != "" {
			err = o.Cmd.Root().GenZshCompletionFile(o.File)
		} else {
			err = o.Cmd.Root().GenZshCompletion(os.Stdout)
		}
	default:
		err = fmt.Errorf("unknown shell: %s. Use bash or zsh", o.Shell)
	}

	if err != nil {
		return errors.E(op, err)
	}

	return nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Use `--shell bash` or `--shell zsh`.
2. For other shells, load bash/zsh completion emulation (e.g. fish's bashenv plugin) or wait for upstream support.

Example fix

# before
hasura completion --shell fish
# after
hasura completion --shell bash

case "$SHELL_FLAG" in bash|zsh) ;; *) echo "unsupported shell: $SHELL_FLAG"; exit 1;; esac

func isSupportedShell(s string) bool { return s == "bash" || s == "zsh" }

Check the message prefix 'unknown shell' and re-run with --shell bash or --shell zsh.

When it happens

Trigger: Running `hasura completion --shell fish` (or powershell, cmd, etc.) — any shell name outside {bash, zsh}, including typos like 'zsh ' or case mismatches depending on the switch.

Common situations: Users assuming fish/pwsh support because other CLIs offer it; copy-pasted docs for a different tool; typo'd flag value.

Related errors

• framework %s is not found
• starter kit is not available for framework %s
• expected a valid url for --api-host, parsing error: %w
• cannot validate new config: %w
• expected extension to be one of %v but got %s on file %s

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/d70c6e9d959cffc6. Report an issue: GitHub.