apache/beam · error

unparsable resource hint: %q

Error message

unparsable resource hint: %q

What it means

GetPipelineResourceHints parses each entry of the ResourceHints job-option slice, which must be in NAME=VALUE form. If a hint string contains no '=' sign, strings.Cut fails and the function panics with 'unparsable resource hint: %q'. This happens at pipeline submission time when the --resource_hints flag value is malformed.

Source

Thrown at sdks/go/pkg/beam/options/jobopts/options.go:202

}

// GetElementProcessingTimeout returns the element processing timeout. If the flag is set to -1,
// there is no timeout.
func GetElementProcessingTimeout() time.Duration {
	if *ElementProcessingTimeout == -1 {
		return 0 * time.Minute
	}
	return *ElementProcessingTimeout
}

// GetPipelineResourceHints parses known standard hints and returns the flag set hints for the pipeline.
// In case of duplicate hint URNs, the last value specified will be used.
func GetPipelineResourceHints() resource.Hints {
	hints := make([]resource.Hint, 0, len(ResourceHints))
	for _, hint := range ResourceHints {
		name, val, ok := strings.Cut(hint, "=")
		if !ok {
			panic(fmt.Sprintf("unparsable resource hint: %q", hint))
		}
		var h resource.Hint
		switch name {
		case "min_ram", "beam:resources:min_ram_bytes:v1":
			h = resource.ParseMinRAM(val)
		case "accelerator", "beam:resources:accelerator:v1":
			h = resource.Accelerator(val)
		case "cpu_count", "beam:resources:cpu_count:v1":
			h = resource.ParseCPUCount(val)
		default:
			if strings.HasPrefix(name, "beam:resources:") {
				h = stringHint{urn: name, value: val}
			} else {
				panic(fmt.Sprintf("unknown resource hint: %v", hint))
			}
		}
		hints = append(hints, h)
	}

View on GitHub (pinned to 12126d8942)

Solutions

1. Correct the hint string to 'name=value' form, e.g. --resource_hints=min_ram=8GiB
2. Check shell quoting/escaping so the '=' and value are not stripped
3. Validate each entry with strings.Contains(hint, "=") before populating jobopts.ResourceHints

Example fix

// before
ResourceHints: []string{"min_ram"}
// after
ResourceHints: []string{"min_ram=8GiB"}

for _, h := range hints {
    if !strings.Contains(h, "=") {
        return fmt.Errorf("resource hint %q must be name=value", h)
    }
}

func isParsableHint(h string) bool { return strings.Contains(h, "=") }

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("resource hints invalid: %v", r)
    }
}()

When it happens

Trigger: Setting jobopts.ResourceHints (e.g. via the --resource_hints flag or programmatically) to a string without '=', such as 'min_ram' or 'accelerator:gpu' instead of 'min_ram=8GiB'.

Common situations: Typos in the --resource_hints CLI flag, shell quoting issues dropping the '=value' part, or building the hints slice programmatically without validating the key=value format.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• unknown resource hint: %v
• The --sdk_location option was used with an unsupported type
• unable to json unmarshal --environment_config: %w
• resource.ParseMinRAM: unable to parse %q: %v
• resource.ParseMaxActiveBundlesPerWorker: unable to parse %q:

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/a1aab223314e7fb9. Report an issue: GitHub.