istio/istio · error

You must provide a proxyID in the query string, e.g. [%s]

Error message

 You must provide a proxyID in the query string, e.g. [%s]

What it means

HandlerForDebugErrors scans responses from istiod's internal debug endpoints. When a response body contains istiod's 'You must provide a proxyID in the query string' message, istioctl surfaces this reminder instead of printing the raw body: the debug request reached istiod but the query lacked the proxyID parameter that endpoint requires (e.g. edsz?proxyID=...).

Source

Thrown at istioctl/pkg/internaldebug/internal-debug.go:72

	}
	if !list {
		_, _ = fmt.Fprint(writer, "error: according to below command list, please check all supported internal debug commands\n")
	}
	return xdsResponses, nil
}

func HandlerForDebugErrors(kubeClient kube.CLIClient,
	centralOpts *clioptions.CentralControlPlaneOptions,
	writer io.Writer,
	istioNamespace string,
	xdsResponses map[string]*discovery.DiscoveryResponse,
) (map[string]*discovery.DiscoveryResponse, error) {
	for _, response := range xdsResponses {
		for _, resource := range response.Resources {
			eString := string(resource.Value)
			switch {
			case strings.Contains(eString, "You must provide a proxyID in the query string"):
				return nil, fmt.Errorf(" You must provide a proxyID in the query string, e.g. [%s]",
					"edsz?proxyID=istio-ingressgateway")

			case strings.Contains(eString, "404 page not found"):
				return HandlerForRetrieveDebugList(false, kubeClient, *centralOpts, writer, istioNamespace)
			}
		}
	}
	return nil, nil
}

func DebugCommand(ctx cli.Context) *cobra.Command {
	var opts clioptions.ControlPlaneOptions
	var centralOpts clioptions.CentralControlPlaneOptions

	debugCommand := &cobra.Command{
		Use:   "internal-debug [<type>/]<name>[.<namespace>]",
		Short: "Retrieves the debug information of istio",
		Long: `

View on GitHub (pinned to 8dc789c5cf)

Solutions

1. Retry with a proxyID: istioctl x internal-debug 'edsz?proxyID=<pod>.<namespace>'
2. Run with --list first to enumerate the supported debug endpoints and their expected arguments
3. Verify the target pod name and namespace are correct so proxyID resolves

Example fix

# before
istioctl x internal-debug edsz
# after
istioctl x internal-debug 'edsz?proxyID=istio-ingressgateway.istio-system'

// Always include proxyID when querying proxy-scoped debug endpoints
if !strings.Contains(debugEndpoint, "proxyID=") {
	debugEndpoint = debugEndpoint + "?proxyID=" + podName + "." + namespace
}

resp, err := HandlerForDebugErrors(kubeClient, centralOpts, w, istioNS, xdsResponses)
if err != nil && strings.Contains(err.Error(), "proxyID") {
	// re-issue the query with a proxyID instead of failing
	return queryDebug(fmt.Sprintf("%s?proxyID=%s.%s", endpoint, pod, ns))
}

When it happens

Trigger: Calling istioctl internal-debug / proxy-config debug endpoints with a resource name that omits the ?proxyID=<pod.namespace> suffix; endpoint requested as a bare type when the istiod handler expects proxy-scoped queries.

Common situations: Exploring istiod debug endpoints via istioctl x internal-debug and guessing endpoint names.

Related errors

• no pods found
• xds address not found
• no pods found
• could not get all scopes: %v
• could not get scopes information: %v

AI-assisted analysis of istio/istio@8dc789c5cf (2026-08-15). Data as JSON: /api/errors/dfa9816792aa0335. Report an issue: GitHub.