What are the DAML and canton process exit codes?

Is there a list of exit codes and reasons for the daml application and canton jar?
e.g. when killed via ctrl + c, sigterm, sigkill etc

We have seen 1, 130 and 252 when killing the daml sandbox or canton processes.

Stretch goal: Is there a graceful way to shutdown/exit the process?

nudge

Hi @Turan
Please use SIGTERM (not SIGKILL) for the graceful shutdown of an application. If SIGTERM doesn’t terminate the process instantly it’s because the application has chosen to handle the signal.
For error codes please refer to error-codes

Hi I meant the system process exit codes not the GRPC ones.

Hi @Turan

As many Users of Canton or Daml will be using a Unix-derived operating system such as MacOS or GNU/Linux I will assume you are also. Apologies if not.

In the Unix world there are 3 core Exit Codes that you might see:

Exit Code 0 = SUCCESS
Exit Code 1 = FAIL (Outright)
Exit Code 2 = Misuse of Shell builtins, incorrect useage

We can check an Exit Code status using the command:

$ echo $?

For info, referring to the Bash Manual (man bash):

$? Expands to the exit status of the most recently executed foreground pipeline.

Which means “Check the exit status of this last command.”

To confirm, I just created a new Daml App using:

$ daml new --template create-daml-app create-daml-app
$ cd create-daml-app
$ daml start
# Wait 30 seconds
$ Ctrl-C
# Check the exit status of this last command
$ echo $?
1

This indicated that the process was terminated and failed.

Then did this:

$ cd .. && rm -rf create-daml-app
$ daml new --template create-daml-app create-daml-app
$ cd create-daml-app
$ echo $?
0

That’s a SUCCESS.

Try something different:

In Terminal_01

$ daml new --template create-daml-app create-daml-app
$ cd create-daml-app
$ daml start
... leave this process running.

In Terminal_02

$ cd ui/
$ npm install
... but interrupt it before it completes the build I get a different error
$ Ctrl-C
$ echo $?
130

Referring to The Linux Documentation Project, Appendix E. Exit Codes with Special Meanings, you see the table that shows the common & reserved Exit Codes.

Exit Code 130 = Script terminated by Control-C; Control-C is fatal error signal 2, (130 = 128 + 2, see above)

As for the Exit Code 252, I am unable to find a specific reference to that, however that does not mean that there is not one. The error codes are range limited, from 0-255. If an error code is potentially greater than 255, the resultant outputted error should be:
255* Exit status out of range.

In terms of a graceful way of terminating a process, if you are currently running a Canton instance, you would type ‘exit’ into the Canton console.

  _____            _
  / ____|          | |
 | |     __ _ _ __ | |_ ___  _ __
 | |    / _` | '_ \| __/ _ \| '_ \
 | |___| (_| | | | | || (_) | | | |
  \_____\__,_|_| |_|\__\___/|_| |_|

  Welcome to Canton!
  Type `help` to get started. `exit` to leave.


@ exit    [ <- Type in EXIT ]

However if you are running a Daml Sandbox, you have 3 easy options:

  • Ctrl-C (Default)
# Check the exit status of this last command
$ echo $?
130
  • Use the command ps aux | grep -i 'canton', ID ProcessID; kill -s SIGTERM ProcessID. (Soft Kill)
# Check the exit status of this last command
$ echo $?
1
  • Use the command ps aux | grep -i 'canton', ID ProcessID; kill -9 ProcessID. (Hard Kill)
# Check the exit status of this last command
$ echo $?
1

Get another Exit Code:

In Terminal_01

$ daml sandbox
Starting Canton sandbox.
Listening at port 6865
Canton sandbox is ready.
... leave this process running.

In Terminal_02

$ ps aux | grep -i 'sandbox'
benm     1950427  0.1  0.0 1074338064 12828 pts/6 Sl+ 16:17 0:00 \
/home/benm/.daml/sdk/2.5.0-snapshot.20221201.11065.0.caac1d10/\
daml-helper/lib/ld-linux-x86-64.so.2 --library-path /home/benm/.daml/\
sdk/2.5.0-snapshot.20221201.11065.0.caac1d10/daml-helper/lib /home\
/benm/.daml/sdk/2.5.0-snapshot.20221201.11065.0.caac1d10/daml-helper\
/lib/daml-helper sandbox
$ kill -9 1950427

Return to Terminal_01

# Check the exit status of this last command
$ echo $?
137

I hope this has helped you to see that the Exit Codes you are seeing while using a Bash Shell in a Unix-derived OS with Canton or Daml are likely to be normal.

As far as a list of specific Exit Codes that applies to the Canton or Daml applications, I will research further and if this does not address your query about Exit Codes, please let me know.