kovidgoyal/kitty · error

Unknown extra argument(s) supplied to %s

Error message

Unknown extra argument(s) supplied to %s

What it means

Generated into the Go handlers for remote control (RC) commands by kitty/rc/base.py: when a command declares args_count == 0 (it takes no positional arguments) but the incoming payload contains positional args, the handler rejects them with this error naming the command.

Source

Thrown at kitty/rc/base.py:227

    args_choices: Callable[[], Iterable[str]] | None = None

    @property
    def args_count(self) -> int | None:
        if not self.spec:
            return 0
        return self.count

    def as_go_completion_code(self, go_name: str) -> Iterator[str]:
        c = self.args_count
        if c is not None:
            yield f'{go_name}.StopCompletingAtArg = {c}'
        if self.completion:
            yield from self.completion.as_go_code(go_name + '.ArgCompleter', ' = ')

    def as_go_code(self, cmd_name: str, field_types: dict[str, str], handled_fields: set[str]) -> Iterator[str]:
        c = self.args_count
        if c == 0:
            yield f'if len(args) != 0 {{ return fmt.Errorf("%s", "Unknown extra argument(s) supplied to {cmd_name}") }}'
            return
        if c is not None:
            yield f'if len(args) != {c} {{ return fmt.Errorf("%s", "Must specify exactly {c} argument(s) for {cmd_name}") }}'
        if self.value_if_unspecified:
            yield 'if len(args) == 0 {'
            for x in self.value_if_unspecified:
                yield f'args = append(args, "{x}")'
            yield '}'
        if self.minimum_count > -1:
            if self.minimum_count == 1:
                yield f'if len(args) < {self.minimum_count} {{ return fmt.Errorf("%s", "Must specify at least one argument to {cmd_name}") }}'
            else:
                yield f'if len(args) < {self.minimum_count} {{ return fmt.Errorf("%s", "Must specify at least {self.minimum_count} arguments to {cmd_name}") }}'
        if self.args_choices:
            achoices = tuple(self.args_choices())
            yield 'achoices := map[string]bool{' + ' '.join(f'"{x}":true,' for x in achoices) + '}'
            yield 'for _, a := range args {'
            yield 'if !achoices[a] { return fmt.Errorf("Not a valid choice: %s. Allowed values are: %s", a, "' + ', '.join(achoices) + '") }'

View on GitHub (pinned to 6d5d0c4406)

Solutions

1. Remove the extra positional arguments from the command
2. Check kitty @ <cmd> --help for the exact argument signature in your version
3. Put values in options/flags (--flag value) rather than positional words when the command expects none
4. Quote and validate constructed command lines in scripts before sending them

Example fix

# before
kitten @ set-window-title main "My Title"

# after
kitten @ set-window-title "My Title"

if cmd.ArgsCount == 0 && len(args) > 0 {
    return fmt.Errorf("%s takes no positional arguments; got %v", cmd.Name, args)
}

func takesNoArgs(argsCount int) bool { return argsCount == 0 }

if err := runRCCommand(cmd, args); err != nil {
    if strings.Contains(err.Error(), "Unknown extra argument") {
        return fmt.Errorf("usage: %s (no positional args)", cmd)
    }
    return err
}

When it happens

Trigger: Sending a remote control command via kitty @ that accepts no positional args but including them, e.g. 'kitten @ new-window extra-arg' for a zero-arg command, or a socket payload whose "args" array is non-empty for a 0-arg command.

Common situations: Scripting kitty @ commands and miscounting which flags vs positional args a command takes; version changes where a command gained/lost positional args; copy-pasted shell commands with trailing words treated as args.

Related errors

• Must specify exactly %s argument(s) for %s
• Unknown type_of_input: {type_of_input}
• Invalid panel options specified: {e}
• Specified password is too long
• %#v is not a valid value for %s. Valid values are: %s

AI-assisted analysis of kovidgoyal/kitty@6d5d0c4406 (2026-08-27). Data as JSON: /api/errors/59731e0f0904863e. Report an issue: GitHub.