What causes "start function failed, please check." in apache/pulsar?

Read the log.Fatal output immediately above the panic — it contains the underlying error.

start function failed, please check.

Error message

start function failed, please check.

What it means

pf.Start builds the function and a Go instance, then starts it. Any error returned by goInstance.startFunction is logged with log.Fatal (which exits) followed by a panic with this message; it indicates the function instance failed to boot (bad handler, config, or broker connectivity handled upstream).

Source

Thrown at pulsar-function-go/pf/function.go:174

//	func ()
//	func () error
//	func (input) error
//	func () (output, error)
//	func (input) (output, error)
//	func (context.Context) error
//	func (context.Context, input) error
//	func (context.Context) (output, error)
//	func (context.Context, input) (output, error)
//
// Where "input" and "output" are types compatible with the "encoding/json" standard library.
// See https://golang.org/pkg/encoding/json/#Unmarshal for how deserialization behaves
func Start(funcName interface{}) {
	function := newFunction(funcName)
	goInstance := newGoInstance()
	err := goInstance.startFunction(function)
	if err != nil {
		log.Fatal(err)
		panic("start function failed, please check.")
	}
}

// GetUserConfMap provides a means to access the pulsar function's user config
// map before initializing the pulsar function
func GetUserConfMap() map[string]interface{} {
	return NewFuncContext().userConfigs
}

// GetUserConfValue provides access to a user configuration value before
// initializing the pulsar function
func GetUserConfValue(key string) interface{} {
	return NewFuncContext().userConfigs[key]
}

View on GitHub (pinned to 820761864e)

Solutions

Read the log.Fatal output immediately above the panic — it contains the underlying error.
Fix the root cause (nil/invalid handler, client/producer setup error).
Test Start() locally with a minimal valid handler before deploying.

Example fix

// before
pf.Start(nil) // panics: start function failed, please check.
// after
pf.Start(func(ctx context.Context, in []byte) ([]byte, error) { return in, nil })

Defensive patterns

Strategy: try-catch

Validate before calling

// recover around startup in a wrapper main
func safeStart(f interface{}) {
    defer func() {
        if r := recover(); r != nil {
            log.Printf("function start failed: %v", r)
            os.Exit(1)
        }
    }()
    pf.Start(f)
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        log.Printf("start function failed: %v", r)
        os.Exit(1)
    }
}()
pf.Start(myFunc)

Prevention

Always read the log.Fatal line preceding the panic — it names the root cause.
Validate the handler and instance config before calling Start.
Smoke-test function startup locally before deploying.

When it happens

Trigger: startFunction returns an error — e.g. the wrapped function was built by errorHandler (nil/invalid handler), or instance setup (client/producer) failed.

Common situations: Misconfigured function passed to Start; invalid handler signature; broker unreachable during instance startup; container entrypoint wiring errors.

Related errors

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