What causes "unknown command or file %q for %q%s" in dagger/dagger?

Check spelling of the subcommand; cobra suggestions appended to the error often list near matches.

unknown command or file %q for %q%s

Error message

unknown command or file %q for %q%s

What it means

Raised by runRoot when the first positional argument of a bare `dagger` invocation is neither a known subcommand nor an existing file path. The root command only auto-forwards to `dagger shell` when args[0] is a file (via isFile); otherwise it reports the unknown argument with cobra suggestions.

Source

Thrown at internal/cmd/dagger/main.go:333

		t.Capture(cmd.Context(), "cli_command", map[string]string{
			"name": commandName(cmd),
		})

		return nil
	},
	RunE: runRoot,
}

func runRoot(cmd *cobra.Command, args []string) error {
	// Historically, the root command fell back to the hidden shell command:
	// `dagger`, `dagger -c ...`, and `dagger file.dsh` all executed shell.
	// Bare `dagger` now prints regular CLI usage, but explicit shell-style root
	// invocations still take the old fallback below.
	if len(args) == 0 && !hasChangedRootShellFlag(cmd) {
		return cmd.Usage()
	}
	if len(args) > 0 && !isFile(args[0]) {
		return fmt.Errorf("unknown command or file %q for %q%s", args[0], cmd.CommandPath(), findSuggestions(cmd, args[0]))
	}
	cmd.SetArgs(append([]string{"shell"}, args...))
	return cmd.Execute()
}

func hasChangedRootShellFlag(cmd *cobra.Command) bool {
	// Cobra stores parsed persistent and local flags together in cmd.Flags().
	// Only root-local flags signal an explicit shell-style invocation; global
	// flags like `--debug` should not keep the old shell fallback.
	changed := false
	persistent := cmd.PersistentFlags()
	cmd.Flags().Visit(func(flag *pflag.Flag) {
		if persistent.Lookup(flag.Name) == nil {
			changed = true
		}
	})
	return changed
}

View on GitHub (pinned to 82ba2681db)

Solutions

Check spelling of the subcommand; cobra suggestions appended to the error often list near matches.
If intending to open a dagger config/file, verify the path exists relative to the current directory.
Run `dagger --help` to list valid commands for this CLI version.

Example fix

// before
dagger sheel
// after
dagger shell

Defensive patterns

Strategy: validation

Validate before calling

arg := os.Args[1]
if !isKnownSubcommand(arg) && !isFile(arg) {
    return fmt.Errorf("%q is not a dagger command or an existing file; see `dagger --help`", arg)
}

Try / catch

if err := runRoot(cmd, args); err != nil { fmt.Fprintln(os.Stderr, err); os.Exit(1) }

Prevention

Tab-complete dagger subcommands instead of typing them.
Run dagger from the directory containing the target file, or use absolute paths.
After upgrading dagger, re-check command names against `dagger --help`.

When it happens

Trigger: Run `dagger <arg>` where `<arg>` is not a registered subcommand and isFile(arg) is false at main.go:333, e.g. a typo or a path to a file that does not exist.

Common situations: Typo in a subcommand name (`dagger sheel`); passing a filename that was deleted or mis-spelled relative to CWD; running an old command name removed in a newer CLI version.

Related errors

AI-assisted analysis of dagger/dagger@82ba2681db (2026-09-05). Data as JSON: /api/errors/31320d7f383955ce. Report an issue: GitHub.