apache/beam · error

unknown resource hint: %v

Error message

unknown resource hint: %v

What it means

GetPipelineResourceHints recognizes only min_ram, accelerator, and cpu_count hints (by short name or full URN); URN-shaped names starting with 'beam:resources:' are accepted as opaque string hints. Any other hint name falls through to a panic with 'unknown resource hint: %v'.

Source

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

	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)
	}
	return resource.NewHints(hints...)
}

// stringHint is a backup implementation of hint for new standard hints.
type stringHint struct {
	urn, value string
}

func (h stringHint) URN() string {
	return h.urn
}

func (h stringHint) Payload() []byte {
	// Go strings are utf8, and if the string is ascii,

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a supported hint name: min_ram, accelerator, or cpu_count
2. For custom hints, use the full URN form starting with 'beam:resources:', e.g. beam:resources:my_hint:v1=value
3. Fix the typo by consulting the Beam resource hints documentation

Example fix

// before
--resource_hints=minram=8GiB
// after
--resource_hints=min_ram=8GiB

valid := map[string]bool{"min_ram": true, "accelerator": true, "cpu_count": true}
for _, h := range hints {
    name, _, ok := strings.Cut(h, "=")
    if !ok || (!valid[name] && !strings.HasPrefix(name, "beam:resources:")) {
        return fmt.Errorf("unknown resource hint %q", name)
    }
}

func isKnownHint(name string) bool {
    switch name {
    case "min_ram", "accelerator", "cpu_count":
        return true
    }
    return strings.HasPrefix(name, "beam:resources:")
}

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

When it happens

Trigger: Passing a hint like --resource_hints=bogus_hint=5 or 'ram=8GiB' whose name is not a known hint and does not start with 'beam:resources:'.

Common situations: Misspelling a hint name (e.g. 'minram' or 'min-ram'), using a hint from a different runner, or inventing a custom hint without the required 'beam:resources:' URN prefix.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unparsable resource hint: %q
• 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/c1d9f6dbd076c693. Report an issue: GitHub.