docker / docker/cli

[RFC] standardise exit-codes

Open
#1,683 4 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area/swarm area/ux kind/enhancement
Dominant language
Go
Stars
6.1k
Forks
2.2k
Avg merge
1d 15h
Merged PRs (30d)
43

Description

Writing this down, as I was thinking about this a while back if there's a way to standardise exit codes (also in light of https://github.com/moby/moby/pull/38689 ("Make client return "rich" errors")), and https://github.com/docker/cli/pull/1674 got me thinking again 😅

The CLI currently uses "chroot" conventions for exit codes, where some exit-codes (> 125) have a special meaning; https://www.tldp.org/LDP/abs/html/exitcodes.html, and exit codes < 125 indicate exit codes from the container's process itself
(see https://github.com/moby/moby/pull/14012)

https://www.tldp.org/LDP/abs/html/exitcodes.html mentions an existing conventions/standard for C/C++.

I was wondering if it would make sense to map (API) errors to those C/C++ standard (if possible); https://github.molgen.mpg.de/git-mirror/glibc/blob/0f1e40d49c1d4871fa9d7b7efdc7fca7f5ac01c0/misc/sysexits.h#L47-L89

Or perhaps there's another standard that makes sense?

For example (this is really a quick "blurb");

Error Exit code (name) Exit code
docker -H tcp://nosuchhost info EX_NOHOST 196 (128+68)
docker service ls (no swarm manager) EX_UNAVAILABLE 197 (128+69)
API returned 403 EX_NOPERM 205 (128+77)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the Docker CLI exit-code conventions described in the issue and the linked moby/moby and docker/cli pull requests. Compare the proposed sysexits.h mappings with the current behavior for container exits, API errors, and unavailable services. Done means the project has agreed on a standard mapping and a concrete implementation scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.