debugging-dubbo-go

name	Debugging dubbo-go
description	Structured diagnosis for dubbo-go runtime errors. Use when user reports an error, paste logs, mentions timeout/panic/connection refused/no provider, or asks why their dubbo-go service isn't working.

Debugging dubbo-go

When user shares an error or log, match it to a pattern below. If unclear, ask for:

1. Full error message or stack trace
2. Registry type (Nacos / ZK / etcd / direct)
3. Protocol (Triple / Dubbo / gRPC)
4. Whether provider and consumer are separate processes

Error Patterns

"no provider available" / "no route"

Cause: Consumer cannot find provider in registry.

Checklist:

• Provider started successfully? Check provider logs for dubbo server started
• Same registry address on both sides (dubbo.WithRegistry(registry.WithAddress(...)) / YAML dubbo.registries.xxx.address)?
• Same application name on both sides (dubbo.WithName(...))? dubbo-go v3 defaults to application-level service discovery — the registry stores the app name, not the interface FQN.
• Same interface name passed into pb.RegisterXxxHandler / pb.NewXxxService on both sides?
• Same protocol on both sides (both tri / both dubbo)?
• Provider visible in the registry (Nacos console / zkCli.sh / etcdctl get --prefix /services)?

# Nacos — v3 default is application-level discovery, so query by app name
curl "http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=<your-app-name>"

---

"connection refused" / dial error

Cause: Network or port configuration error.

Checklist:

• Provider port in protocols.triple.port matches what consumer is trying to connect to?
• Firewall / Docker network allowing the port?
• If Docker: using container name, not localhost?
• Provider actually listening? lsof -i :20000

---

Serialization / decode error

hessian: failed to decode
protobuf: cannot parse invalid wire-format data

Cause: Provider and consumer using different serialization formats.

Checklist:

• Both sides using same protocol (both tri or both dubbo)?
• If Protobuf: same .proto file compiled on both sides? Same go_package?
• If Dubbo/Hessian2: POJO class names match between Go struct tags and Java class?

---

Timeout

context deadline exceeded
invoke timeout

Cause: Provider too slow, filter blocking, or network delay.

Checklist:

• Is provider actually receiving the request? (add log in handler)
• Any filter that might block? (auth, token, tps-limit)
• Timeout value configured too low?

// Code API: set per-reference timeout
svc, _ := pb.NewGreetService(cli, client.WithRequestTimeout(10*time.Second))

// Or at call site with a standard context:
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
resp, err := svc.Greet(ctx, req)

---

"filter not found" / filter panic

Cause: Filter imported but not registered, or name string doesn't match what was registered in extension.SetFilter(name, ...).

Checklist:

• Blank import present? e.g., _ "dubbo.apache.org/dubbo-go/v3/filter/token" or _ "github.com/yourorg/yourapp/filter/myfilter"
• String passed to server.WithFilter("xxx") / client.WithClientFilter("xxx") matches the name used in the extension.SetFilter("xxx", ...) call inside that filter's init()?
• Built-in filter not pulled in? Use _ "dubbo.apache.org/dubbo-go/v3/imports" during development to auto-import all built-in filters.

---

Provider starts but immediately exits

Cause: Missing srv.Serve() or wrong graceful shutdown setup.

// Correct: blocking call
if err := srv.Serve(); err != nil {
    panic(err)
}

// Wrong: non-blocking, process exits immediately
go srv.Serve()
// nothing blocks here → process exits

---

Reading dubbo-go logs

Enable debug logging to see more detail:

// import "dubbo.apache.org/dubbo-go/v3/logger"
ins, _ := dubbo.NewInstance(
    dubbo.WithLogger(logger.WithLevel("debug")),
    // ...
)

Key log lines to look for:

• Registering service: <interface> — service being registered
• A provider service ... was registered successfully — provider ready
• export <interface> service failed — registration error
• No provider available / no route — consumer lookup failed