errors

README

Docker 'errors' package

This package contains all of the error messages generated by the Docker engine that might be exposed via the Docker engine's REST API.

Each top-level engine package will have its own file in this directory so that there's a clear grouping of errors, instead of just one big file. The errors for each package are defined here instead of within their respective package structure so that Docker CLI code that may need to import these error definition files will not need to know or understand the engine's package/directory structure. In other words, all they should need to do is import .../docker/api/errors and they will automatically pick up all Docker engine defined errors. This also gives the engine developers the freedom to change the engine packaging structure (e.g. to CRUD packages) without worrying about breaking existing clients.

These errors are defined using the 'errcode' package. The errcode package allows for each error to be typed and include all information necessary to have further processing done on them if necessary. In particular, each error includes:

• Value - a unique string (in all caps) associated with this error. Typically, this string is the same name as the variable name of the error (w/o the ErrorCode text) but in all caps.

• Message - the human readable sentence that will be displayed for this error. It can contain '%s' substitutions that allows for the code generating the error to specify values that will be inserted in the string prior to being displayed to the end-user. The WithArgs() function can be used to specify the insertion strings. Note, the evaluation of the strings will be done at the time WithArgs() is called.

• Description - additional human readable text to further explain the circumstances of the error situation.

• HTTPStatusCode - when the error is returned back to a CLI, this value will be used to populate the HTTP status code. If not present the default value will be StatusInternalServerError, 500.

Not all errors generated within the engine's executable will be propagated back to the engine's API layer. For example, it is expected that errors generated by vendored code (under docker/vendor) and packaged code (under docker/pkg) will be converted into errors defined by this package.

When processing an errcode error, if you are looking for a particular error then you can do something like:

import derr "github.com/docker/docker/api/errors"

...

err := someFunc()
if err.ErrorCode() == derr.ErrorCodeNoSuchContainer {
	...
}

Documentation

Index

• Variables

Variables

var (
	// ErrorCodeAtLeastOneArg is generated when the parser comes across a
	// Dockerfile command that doesn't have any args.
	ErrorCodeAtLeastOneArg = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "ATLEASTONEARG",
		Message:        "%s requires at least one argument",
		Description:    "The specified command requires at least one argument",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeExactlyOneArg is generated when the parser comes across a
	// Dockerfile command that requires exactly one arg but got less/more.
	ErrorCodeExactlyOneArg = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "EXACTLYONEARG",
		Message:        "%s requires exactly one argument",
		Description:    "The specified command requires exactly one argument",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeAtLeastTwoArgs is generated when the parser comes across a
	// Dockerfile command that requires at least two args but got less.
	ErrorCodeAtLeastTwoArgs = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "ATLEASTTWOARGS",
		Message:        "%s requires at least two arguments",
		Description:    "The specified command requires at least two arguments",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeTooManyArgs is generated when the parser comes across a
	// Dockerfile command that has more args than it should
	ErrorCodeTooManyArgs = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "TOOMANYARGS",
		Message:        "Bad input to %s, too many args",
		Description:    "The specified command was passed too many arguments",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeChainOnBuild is generated when the parser comes across a
	// Dockerfile command that is trying to chain ONBUILD commands.
	ErrorCodeChainOnBuild = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "CHAINONBUILD",
		Message:        "Chaining ONBUILD via `ONBUILD ONBUILD` isn't allowed",
		Description:    "ONBUILD Dockerfile commands aren't allow on ONBUILD commands",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeBadOnBuildCmd is generated when the parser comes across a
	// an ONBUILD Dockerfile command with an invalid trigger/command.
	ErrorCodeBadOnBuildCmd = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "BADONBUILDCMD",
		Message:        "%s isn't allowed as an ONBUILD trigger",
		Description:    "The specified ONBUILD command isn't allowed",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeMissingFrom is generated when the Dockerfile is missing
	// a FROM command.
	ErrorCodeMissingFrom = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "MISSINGFROM",
		Message:        "Please provide a source image with `from` prior to run",
		Description:    "The Dockerfile is missing a FROM command",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeNotOnWindows is generated when the specified Dockerfile
	// command is not supported on Windows.
	ErrorCodeNotOnWindows = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "NOTONWINDOWS",
		Message:        "%s is not supported on Windows",
		Description:    "The specified Dockerfile command is not supported on Windows",
		HTTPStatusCode: http.StatusInternalServerError,
	})

	// ErrorCodeVolumeEmpty is generated when the specified Volume string
	// is empty.
	ErrorCodeVolumeEmpty = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "VOLUMEEMPTY",
		Message:        "Volume specified can not be an empty string",
		Description:    "The specified volume can not be an empty string",
		HTTPStatusCode: http.StatusInternalServerError,
	})
)

var (
	// ErrorCodeNoSuchContainer is generated when we look for a container by
	// name or ID and we can't find it.
	ErrorCodeNoSuchContainer = errcode.Register(errGroup, errcode.ErrorDescriptor{
		Value:          "NOSUCHCONTAINER",
		Message:        "no such id: %s",
		Description:    "The specified container can not be found",
		HTTPStatusCode: http.StatusNotFound,
	})
)