FAQ

If your needs cannot be met, please submit an issue on the Kitex GitHub repository, and the community maintainers will promptly follow up and address it.

Kitex Framework

Q1: Does Kitex support Windows？

• Yes. Kitex has already supported to compile and run in Windows since v0.4.0 version. And code generation tool support the Windows environment since v0.5.2.

Q2: Does Kitex support HTTP？

• Kitex does not specifically provide HTTP request support. For API gateway scenario, Kitex provides a HTTP mapping generic call regarding Thrift and sends the Thrift encoding of the HTTP request to the server.
• For related support, please refer to another CloudWeGo HTTP framework Hertz.

Q3: How to configure multiplexing?

• If you are using Thrift or Kitex Protobuf, to configure multiplexing:
  1. Configure WithMuxTransport() on your server.
  2. Configure WithMuxConnection(1) on your client
• If you are using gRPC, multiplexing is configured by default.

Q4: In the scenario of direct local call, why does the configuration of connection pool not take effect?

• The ip of your local test needs to be 127.0.0.1. For example, “client.WithHostPorts(“127.0.0.1:8888”)”.

Q5: What are the differences between “Kitex Protobuf” and “gRPC” protocol?

• Kitex Protobuf is a Protobuf Message Protocol defined by Kitex framework, with similar structure to Thrift.
• gRPC provides support to gRPC message protocol and enables Kitex to interact with gRPC framework.

Q6: Issues regarding Thrift interface compiling, such as “not enough arguments in call to iprot.ReadStructBegin”

• Based on Thrift v0.13, Kitex cannot be upgraded directly, as there is a breaking change in the interface of Apache Thrift v0.14. The reason for such problems could be that a new version of Thrift is pulled during upgrades. The use of -u parameters is not recommended during upgrades, you can run the following command to fix the version: go mod edit -replace github.com/apache/thrift=github.com/apache/thrift@v0.13.0

Kitex Code Generation Tool

Q1:‘not enough arguments’ problem when installing the code generation tool

• Please try: “go mod：GO111MODULE=on go get github.com/cloudwego/kitex/tool/cmd/kitex@latest”

Q2: Why ‘set’ in IDL becomes slice in generated codes?

• Considering from JSON serialization, Starting from v0.11.0, Apache Thrift officially changes the generation type of set from map to slice. From a compatibility perspective, Kitex also follows the same rule.

Q3: Why is there an underscore after some field names?

• The official implementation of Thrift restricts identifiers ending in “Result” and “Args” to avoid naming conflicts. The official Thrift conflict avoidance strategy: when the type name, service name and method name in the Thrift file start with New or end with Result or with Args, Thrift will automatically add an underscore at the end of the name. Referring to https://jira.apache.org/jira/browse/THRIFT-4410, Kitex uses Thriftgo for code generation. Thriftgo adopts a similar strategy in order to be as consistent as possible with the official implementation.

Q4: Would code generated by new interface overwrite handler.go

• Generated code under kitex_gen/ will be overwritten. But handler.go of server will not be overwritten, only new methods will be added correspondingly.

Q5: Do the templates of the code generator support customization?

• We have no plan to support template customization at present, because it will make the design for parameter passing much more complex. And the plugin mechanism can achieve almost any functionality equivalent to a customized template.

Q6: Is it possible for the ‘-type’ argument of the code generator to be determined automatically by IDL filename extension?

CPU Utilization Soaring

Hotspot Issue with error.Is\As

According to the CPU profile, there is a hotspot issue with errors.Is or errors.As, and the CPU usage even reaches its maximum.

Cause: The custom error type has implemented the Unwrap method, but the implementation is incorrect. It returns the error object itself, causing an infinite loop. Here is an example:

func (e *XError) Unwrap() error {
   if e == nil {
      return nil
   }
   return e.InnerError // Actually returns itself
}

func (e *XError) NewXError(outMsg *XError) *XError {
   err := &XError{
      OutCode:    outMsg.OutCode,
      OutMsg:     outMsg.OutMsg,
      InnerError: innerErr(outMsg.Msg),
   }
   err.InnerError = err // Points to itself here
   return err
}

Solution: The Unwrap method should return the wrapped error instead of itself. If there is no wrapped error, it should return nil. Avoid circular references.

Timeout Errors

Context Deadline Earlier Than Timeout

Cause: The Kitex client handles request timeouts based on the context provided by context.WithTimeout(ctx, timeout). If the ctx passed from the business logic already has a deadline set and it is earlier than the RPC timeout, the ctx deadline from the business logic will be used.

Solution: Do not set deadline for the ctx used by Kitex.

Troubleshooting:

• Use the context.Done() method: Before the RPC request, output the following information about the ctx. If ctx.Done() != nil, it indicates that WithTimeout or WithDeadline has been set.

deadline, _ := ctx.Deadline()
klog.Infof("before rpc call, ctxDone=%t, deadline=%v", ctx.Done() != nil, deadline)

• Identify the places in the code where WithTimeout, WithDeadline, or equivalent operations are called. Sometimes you may not directly set the timeout. It is common to pass the ctx used by another framework to the kitex client, and that ctx has already been modified with the mentioned operations. Regardless of who made the modification, trace back the assignment of ctx starting from the code segment where the call to Client is made, and you will find the point of tampering. You can use dlv (the Go debugger) or the debugging mode of your IDE to help trace the call chain.

Context Canceled by Business

Cause: If the business code calls the cancel function returned by WithTimeout, WithDeadline, or WithCancel before the actual timeout deadline set by the Kitex client, Kitex will append additional information stating context canceled by business.

Troubleshooting: Refer to the troubleshooting method for “Context Deadline Earlier Than Timeout”.

Note: If multiple goroutines share the same ctx (typical when starting a new goroutine and passing the ctx to it), calling the cancel method of that ctx will affect all goroutines.

Invalid Payload Error

This error indicates a protocol mismatch between the client and server. Below are some common scenarios for reference.

To quickly determine whether the issue lies with the client or server, you can consider the following:

• If the error occurs only on the client side, it suggests that the server’s response does not meet the expected format.
  • For example, if the client requested an HTTP server and received a response starting with “HTTP/1.1”.
• If the error occurs only on the server side, it suggests that the server received a request that does not meet the expected format.
  • For example, if the server received a request starting with “GET " or “POST” from an HTTP client.

Q1: How to identify the source of the request?

• It is recommended to identify the request source based on the client’s IP address.

Q2: Why doesn’t the error message include the method name of the request?

• The error message doesn’t include the method name because the request does not contain a valid RPC payload. Kitex cannot parse it, so it doesn’t know which method was requested (the protocol of the message is incorrect, indicating that it is likely not requesting a specific RPC method).