Frequently Asked Questions

Wrong version between Keikai client and engine

When you visit a page with Keikai, if you see the error:

That means the version of Keikai Java client is inconsistent with the engine. The message also tells you both the client and engine version you use. You need to make both version consistent, so you can either:

  • Contact us to download another version of Keikai engine
  • Change Keikai client version to match engine’s

How to change the Keikai client version:

Just modify the version string in the corresponding file depending on which tool you run this project.






compile "io.keikai:keikai-java-client:*-Eval"

Import Larger Files

Importing larger files require a larger heap size. Here are peak heap size consumed by an application server. Please reference it to specify your server’s heap size.

File size Number of Cells Peak Heap Size
10 MB 1.4 millions 1.5G
20 MB 2.9 millions 1.9G
40 MB 8.7 millions 2.5G

If you wish to try importing large files, please increase your heap size accordingly. You can increase the heap size with JVM arguments:


gradle appRun -Dorg.gradle.jvmargs=-Xmx4g


modify the configurations of jetty-maven-plugin in pom.xml


please refer to

Start Keikai engine with different port and address

./keikai -—port=9999 -—address=

  • For complete options, you can check with the command: ./keikai --help

Connect to a Different Keikai engine Address

By default, this project connects to a Keikai engine at localhost:8888. If you wish to connect to a different address, please append a query string with the server key:


How to start the tutorial project with gradle

Linux / Mac

Gradle wrapper

./gradlew appRun


Gradle wrapper

gradlew appRun

Maximal column/row of a sheet

Just like Excel:

  • Maximal column number: 16,384 (XFD)
  • Maximal row number: 1,048,576

How to debug

Range API runtime error

Since Keikai client API actually sends a command to a Keikai engine to execute operations remotely instead of executing it locally. So such the error caused by setter API can’t show a line number of your program. For example, if you call a Keikai java client API, and it produces an error. Please scoll down to check the last error stack trace:

socketPool-2-eventThread-1] ERROR io.keikai.client.kms.KMSClient - Remote server runtime error: ca3q13499ub36:["{"winId":"ca3q13499ub36","cmd":"Range.setValue","data":{"sheetId":"*nuv0HGJiwkBd4.XeDZOOTXPp","range":"a1a","bookName":"Book1.xlsx","value":"a1s"}}"]
Bad state: No element
#0      ...

Then You can check "cmd":"Range.setValue", "range":"a1a" in that Json data, that means you the error is caused by Range.setValue() and the range is a1a. So you can search you code with the detail and found the root cause:

setting value on a non-existed cell: spreadsheet.getRange("a1a").setValue("123");

Session Timeout

Keikai keeps sending requests to an application server to avoid session timeout.

If there is a proxy server between your application and browsers, and you see such message:

The action you request is no longer available.
This is normally caused by timeout.
You have to reload the page and try again.

Open developer tool to check if there is an error similar like: POST http://localhost:8080/appContextPath/kk 404 (Not Found)

That’s because the proxy maps [path-a] to [path-b] so that keikai keep-alive request doesn’t send to the correct path. Then finally a session expires.

You need to specify the target context path:

        Settings settings = Settings.DEFAULT_SETTINGS.clone();
        settings.set(Settings.Key.CONTEXT_PATH, "TheRealApplicationContentPath");
        Keikai.newClient(keikaiServerAddress, settings);

Support to Run VB macro?

No. Even Microsoft Excel online doesn’t support running VB macro (Please see Editing files with VBA or here).

If you need do something similar, you need to port your VB macro to Java within event listeners.

Evaluation Engine

When starting up a Keikai engine under this state, there is a limited trial time message:

INFO: This is an evaluation copy of Keikai 1.0.0@jvw6wenz. 
Your trial will end at "2019/08/19 00:00:00", if you wish to continue using Keikai please contact us at
1:8888:2019-06-26 06:49:44.009437Z:stream:4

Besides, you should see a evaluation mark at the right-bottom corner of each sheet:

Expired Engine

If you start an engine whose trial period expired, you will see the messsage below:

INFO: This is an evaluation copy of Keikai 1.0.0-beta.11@jqlrv3br. 
The trial period has expired, please contact us at for assistance.

Then the engine will exit.

Licensed Engine

Each machine requires one license. If you run 2 engines on 2 different machines, you need to accquire 2 different licenses for 2 machines.

Install a License File

  • Default Path

put the license file under a specific folder in Keikai engine: keikai/license

  • Custom Path

specify the license folder when running a Keikai engine.

./keikai --lic-dir=AbsolutePath

If you install a license file successfully, you should see the your license information like the one below when you start a Keikai engine:

Keikai Engine Installed Licenses: 1

*** Potix Corporation License Information (0) ***

  Licensed Company: Test Compnay
  Certificate Number: 123456789       
  Licensed Product: keikai component
  Maximum Licensed Number: 1 installation
  API Key: abcdefghiojklmnop
  Extended Trial until Oct. 10, 2029

Java Client Requires an API key

In your license information, you can see there is an API key printed:

API Key: abcdefghiojklmnop

To connect to a licensed engine, you should create a Java client with the matched API key:

Settings settings = Settings.DEFAULT_SETTINGS.clone();
settings.set(Settings.Key.API_KEY, "abcdefghiojklmnop");

spreadsheet = Keikai.newClient(keikaiEngineAddress, settings);

If you connect the engine without a valid key (or without key), you will see the error message in your application server console and browser:

io.keikai.client.kms.KMSException: The API key is invalid. 
Please contact us at to obtain a valid API key.
Caused by null

Inconsistent License File

Each license file is generated for a specific machine. If you install the license file to another machine, you will see the error below when you start the engine:

WARNING: The license issued to "MyCompanyName" with "a-long-keikai-engine-serial-number" has a wrong Keikai engine serial number. 
Please contact to obtain a valid license.
License file: license\Keikai_License_Signature_For_MyCompany.19062615