the `--query` flag is not supported on this GitHub host

Error message

the `--query` flag is not supported on this GitHub host

What it means

item-list's --query flag relies on a GitHub Projects feature (ProjectItemQuery) detected per host via config.detector.ProjectFeatures(). On hosts where the detector reports the capability absent (typically older GHES), passing --query fails fast with this message before fetching items.

Source

Thrown at pkg/cmd/project/item-list/item_list.go:140

	listCmd.Flags().StringVar(&opts.owner, "owner", "", "Login of the owner. Use \"@me\" for the current user")
	listCmd.Flags().StringVar(&opts.query, "query", "", `Filter items using the Projects filter syntax, e.g. "assignee:octocat -status:Done"`)
	listCmd.Flags().StringArrayVar(&opts.fields, "field", nil, "Name of a field to show as an extra column")
	listCmd.Flags().StringArrayVar(&opts.fieldIDs, "field-id", nil, "ID of a field to show as an extra column")
	cmdutil.AddFormatFlags(listCmd, &opts.exporter)
	listCmd.Flags().IntVarP(&opts.limit, "limit", "L", queries.LimitDefault, "Maximum number of items to fetch")

	return listCmd
}

func runList(config listConfig) error {
	if config.opts.query != "" {
		features, err := config.detector.ProjectFeatures()
		if err != nil {
			return err
		}
		if !features.ProjectItemQuery {
			return fmt.Errorf("the `--query` flag is not supported on this GitHub host")
		}
	}

	canPrompt := config.io.CanPrompt()
	owner, err := config.client.NewOwner(canPrompt, config.opts.owner)
	if err != nil {
		return err
	}

	// no need to fetch the project if we already have the number
	if config.opts.number == 0 {
		project, err := config.client.NewProject(canPrompt, owner, config.opts.number, false)
		if err != nil {
			return err
		}
		config.opts.number = project.Number
	}

View on GitHub (pinned to 0eeec0b92e)

Solutions

Drop --query and filter client-side after fetching items (e.g. with --json and --jq on the local result)
Run the command against github.com if that is where the project lives (check -R/host config)
Upgrade GHES to a version supporting project item queries

Example fix

# before
gh project item-list 1 --query 'status:"Done"'
# after (client-side filter on GHES)
gh project item-list 1 --json title,createdAt --jq '.[] | select(.title | contains("Done"))'

Defensive patterns

Strategy: validation

Validate before calling

if host != "github.com" && flagQuery != "" {
    return errors.New("--query unsupported on this host; filter with --jq client-side")
}

Try / catch

if strings.Contains(err.Error(), "--query` flag is not supported") {
    return runWithoutQueryAndFilterLocally()
}

Prevention

Feature-detect per host before using newer flags in portable scripts
Prefer --json plus --jq post-filtering for cross-host compatibility
Keep separate script paths for github.com and GHES

When it happens

Trigger: Running `gh project item-list <number> --query '...'` against a GHES instance whose version does not support project item querying via the newer API surface.

Common situations: Scripts developed against github.com then run against GHES, or after a GHES upgrade changed feature flags; users assume feature parity between github.com and GHES.

Related errors

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/4f5d117197bb306d. Report an issue: GitHub.