Go instance current not support EFFECTIVELY_ONCE processing

Error message

Go instance current not support EFFECTIVELY_ONCE processing guarantees.

What it means

The Go function runtime does not implement EFFECTIVELY_ONCE processing guarantees. newInstanceConfWithConf proactively panics at config load when the function details request it, so the operator knows immediately that the requested guarantees are unsupported rather than silently weakening delivery semantics.

Source

Thrown at pulsar-function-go/pf/instanceConf.go:138

		},
		authPlugin:              cfg.ClientAuthenticationPlugin,
		authParams:              cfg.ClientAuthenticationParameters,
		tlsTrustCertsPath:       cfg.TLSTrustCertsFilePath,
		tlsAllowInsecure:        cfg.TLSAllowInsecureConnection,
		tlsHostnameVerification: cfg.TLSHostnameVerificationEnable,
	}
	// parse the raw function details and ignore the unmarshal error(fallback to original way)
	if cfg.FunctionDetails != "" {
		functionDetails := pb.FunctionDetails{}
		if err := protojson.Unmarshal([]byte(cfg.FunctionDetails), &functionDetails); err != nil {
			log.Errorf("Failed to unmarshal function details: %v", err)
		} else {
			instanceConf.funcDetails = functionDetails
		}
	}

	if instanceConf.funcDetails.ProcessingGuarantees == pb.ProcessingGuarantees_EFFECTIVELY_ONCE {
		panic("Go instance current not support EFFECTIVELY_ONCE processing guarantees.")
	}

	if !instanceConf.funcDetails.AutoAck && //nolint:staticcheck
		(instanceConf.funcDetails.ProcessingGuarantees == pb.ProcessingGuarantees_ATMOST_ONCE ||
			instanceConf.funcDetails.ProcessingGuarantees == pb.ProcessingGuarantees_ATLEAST_ONCE) {
		panic("When Guarantees == " + instanceConf.funcDetails.ProcessingGuarantees.String() +
			", autoAck must be equal to true. If you want not to automatically ack, " +
			"please configure the processing guarantees as MANUAL." +
			" This is a contradictory configuration, autoAck will be removed later." +
			" Please refer to PIP: https://github.com/apache/pulsar/issues/15560")
	}

	return instanceConf
}

func newInstanceConf() *instanceConf {
	config := &conf.Conf{}
	cfg := config.GetConf()

View on GitHub (pinned to 820761864e)

Solutions

Switch ProcessingGuarantees to ATLEAST_ONCE (or ATMOST_ONCE) in the function config.
Use a Java/Python function if EFFECTIVELY_ONCE is mandatory.
Keep Go runtime updated and check whether newer versions add support before retrying.

Example fix

// before
processingGuarantees: EFFECTIVELY_ONCE // unsupported in Go
// after
processingGuarantees: ATLEAST_ONCE

Defensive patterns

Strategy: validation

Validate before calling

if details.ProcessingGuarantees == pb.ProcessingGuarantees_EFFECTIVELY_ONCE {
    return fmt.Errorf("Go functions do not support EFFECTIVELY_ONCE; use ATLEAST_ONCE")
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        if s, ok := r.(string); ok && strings.Contains(s, "EFFECTIVELY_ONCE") {
            log.Fatalf("unsupported guarantees for Go runtime: %s", s)
        }
        panic(r)
    }
}()

Prevention

Set ATLEAST_ONCE in function configs targeting the Go runtime.
Reject EFFECTIVELY_ONCE in CI checks on function manifests.
Choose the Java runtime when effectively-once semantics are required.

When it happens

Trigger: Deploying a Go function (or a Go instance started via pf) whose FunctionDetails set ProcessingGuarantees to EFFECTIVELY_ONCE.

Common situations: Function config copied from a Java function using effectively-once with transactions; tooling defaults changed; user assuming feature parity across runtimes.

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/0623aa2f4732c43b. Report an issue: GitHub.