derailed/k9s · error

invalid command. use `xray xxx`

Error message

invalid command. use `xray xxx`

What it means

Returned by `Command.xrayCmd` (internal/view/command.go:~149) when the command interpreter reports no argument for the `xray` command (`p.XrayArgs()` returns ok=false). k9s' xray view needs a resource name to traverse, so `xray` with no target is rejected before anything else runs. Subsequent guards (alias resolution, allowlist) produce their own errors; this one is purely the missing-argument case.

Source

Thrown at internal/view/command.go:149

		p.SwitchNS(ns)
	}

	return false
}

func (c *Command) aliasCmd(p *cmd.Interpreter, pushCmd bool) error {
	filter, _ := p.FilterArg()

	v := NewAlias(client.AliGVR)
	v.SetFilter(filter, true)

	return c.exec(p, client.AliGVR, v, false, pushCmd)
}

func (c *Command) xrayCmd(p *cmd.Interpreter, pushCmd bool) error {
	arg, cns, ok := p.XrayArgs()
	if !ok {
		return errors.New("invalid command. use `xray xxx`")
	}
	if c.alias == nil {
		return fmt.Errorf("no connection available")
	}
	gvr, ok := c.alias.Resolve(cmd.NewInterpreter(arg))
	if !ok {
		return fmt.Errorf("invalid resource name: %q", arg)
	}
	if !allowedXRay(gvr) {
		return fmt.Errorf("unsupported resource %q", arg)
	}
	ns := c.app.Config.ActiveNamespace()
	if cns != "" {
		ns = cns
	}
	if err := c.app.Config.SetActiveNamespace(client.CleanseNamespace(ns)); err != nil {
		return err
	}

View on GitHub (pinned to 2d3ccc6ba2)

Solutions

1. Provide a resource: `:xray po`, `:xray deploy`, `:xray svc`, `:xray ns`
2. Check allowed targets with allowedXRay if unsure which resources the current k9s version supports
3. Fix any custom alias that invokes xray without its argument

Example fix

# before
:xray
# -> invalid command. use `xray xxx`
# after
:xray deploy

// Verify the argument exists before dispatching:
if len(strings.Fields(cmdString)) < 2 || !strings.HasPrefix(cmdString, "xray ") {
    return errors.New("invalid command. use `xray xxx`")
}

func hasXrayArg(args []string) bool {
    return len(args) >= 1 && strings.TrimSpace(args[0]) != ""
}

When it happens

Trigger: Typing `:xray` and hitting enter in the command prompt with no argument, or a command alias that expands to bare `xray`. `cmd.Interpreter.XrayArgs()` fails to extract the resource token.

Common situations: New users exploring `:xray` without knowing it takes an argument; typos like `:xray` instead of `:xray po`; scripts/aliases configured with a bare xray.

Related errors

• invalid command use `context xxx`
• invalid resource name: %q
• unsupported resource %q
• expecting a TreeNode but got %T
• expecting *Unstructured but got %T

AI-assisted analysis of derailed/k9s@2d3ccc6ba2 (2026-08-15). Data as JSON: /api/errors/7ca341bbd44f945b. Report an issue: GitHub.