Exceptions

Exceptions are defined in three different modules in the craft_parts package.

General errors

Exceptions for general errors are defined in the craft_parts.errors module.

Craft parts errors.

exception craft_parts.errors.BuildSlicesEnvironmentError

Bases: PartsError

The build-slices environment is missing essential files.

exception craft_parts.errors.CallbackRegistrationError(message)

Bases: PartsError

Error in callback function registration.

Parameters:

message (str) – the error message.

exception craft_parts.errors.CopyFileNotFound(name)

Bases: PartsError

An attempt was made to copy a file that doesn’t exist.

Parameters:

name (str) – The file name.

exception craft_parts.errors.CopyTreeError(message)

Bases: PartsError

Failed to copy or link a file tree.

Parameters:

message (str) – The error message.

exception craft_parts.errors.DebError(deb_path, command, exit_code)

Bases: PartsError

A “deb”-related command failed.

Parameters:

• deb_path (Path)

• command (list[str])

• exit_code (int)

exception craft_parts.errors.FeatureError(message, details=None)

Bases: PartsError

A feature is not configured as expected.

Parameters:

• message (str)

• details (str | None)

exception craft_parts.errors.FileOrganizeError(*, part_name, message)

Bases: PartsError

Failed to organize a file layout.

Parameters:

• part_name (str) – The name of the part being processed.

• message (str) – The error message.

classmethod from_merge_conflicts(*, part_name, key, destination, conflicts)

Create from directory merge conflicts.

Parameters:

• part_name (str) – The name of the part being processed.

• key (str) – The organize key (source pattern).

• destination (str) – The organize destination value.

• conflicts (dict[Path, list[str]]) – A mapping of paths to their conflict descriptions.

Return type:

FileOrganizeError

exception craft_parts.errors.FilesetConflict(conflicting_files)

Bases: PartsError

Inconsistent stage to prime filtering.

Parameters:

conflicting_files (set[str]) – A set containing the conflicting file names.

exception craft_parts.errors.FilesetError(*, name, message)

Bases: PartsError

An invalid fileset operation was performed.

Parameters:

• name (str) – The name of the fileset.

• message (str) – The error message.

exception craft_parts.errors.FilesystemMountError(brief, *, details=None, resolution=None)

Bases: PartsError

Errors related to filesystem mounts.

Parameters:

• brief (str)

• details (str | None)

• resolution (str | None)

classmethod from_validation_error(*, error_list)

Create a FilesystemMountError from a pydantic error list.

Parameters:

error_list (list[ErrorDetails]) – A list of dictionaries containing pydantic error definitions.

Return type:

FilesystemMountError

exception craft_parts.errors.InvalidAction(message)

Bases: PartsError

An attempt was made to execute an action with invalid parameters.

Parameters:

message (str) – The error message.

exception craft_parts.errors.InvalidApplicationName(name)

Bases: PartsError

The application name contains invalid characters.

Parameters:

name (str) – The invalid application name.

exception craft_parts.errors.InvalidArchitecture(arch_name)

Bases: PartsError

The machine architecture is not supported.

Parameters:

arch_name (str) – The unsupported architecture name.

exception craft_parts.errors.InvalidControlAPICall(*, part_name, scriptlet_name, message)

Bases: PartsError

A control API call was made with invalid parameters.

Parameters:

• part_name (str) – The name of the part being processed.

• scriptlet_name (str) – The name of the scriptlet that originated the call.

• message (str) – The error message.

exception craft_parts.errors.InvalidPartName(part_name)

Bases: PartsError

An operation was requested on a part that’s not in the parts specification.

Parameters:

part_name (str) – The invalid part name.

exception craft_parts.errors.InvalidPlugin(plugin_name, *, part_name)

Bases: PartsError

A request was made to use a plugin that’s not registered.

Parameters:

• plugin_name (str) – The invalid plugin name.”

• part_name (str) – The name of the part defining the invalid plugin.

exception craft_parts.errors.OsReleaseCodenameError

Bases: PartsError

Failed to determine the host operating system version codename.

exception craft_parts.errors.OsReleaseIdError

Bases: PartsError

Failed to determine the host operating system identification string.

exception craft_parts.errors.OsReleaseNameError

Bases: PartsError

Failed to determine the host operating system name.

exception craft_parts.errors.OsReleaseVersionIdError

Bases: PartsError

Failed to determine the host operating system version.

exception craft_parts.errors.OverlayPackageNotFound(*, part_name, package_name)

Bases: PartsError

Failed to install an overlay package.

Parameters:

• part_name (str) – The name of the part being processed.

• message – the error message.

• package_name (str)

exception craft_parts.errors.OverlayPermissionError

Bases: PartsError

A project using overlays was processed by a non-privileged user.

exception craft_parts.errors.OverlayPlatformError

Bases: PartsError

A project using overlays was processed on a non-Linux platform.

exception craft_parts.errors.OverlayStageConflict(*, part_name, overlay_part_name, conflicting_files, partition=None)

Bases: PartsError

A conflict between contents to be staged from the overlay and from the build step.

Parameters:

• part_name (str)

• overlay_part_name (str)

• conflicting_files (list[Path])

• partition (str | None)

exception craft_parts.errors.PartDependencyCycle(*, part_names=None)

Bases: PartsError

A dependency cycle has been detected in the parts definition.

Parameters:

part_names (list[str] | None) – The names of the parts involved in the cycle.

exception craft_parts.errors.PartFilesConflict(*, part_name, other_part_name, conflicting_files, partition=None)

Bases: PartsError

Different parts list the same files with different contents.

Parameters:

• part_name (str) – The name of the part being processed.

• other_part_name (str) – The name of the conflicting part.

• conflicting_files (list[Path]) – The list of conflicting files.

• partition (str | None) – Optional name of the partition where the conflict occurred.

exception craft_parts.errors.PartNameConflict(*, part_name, conflicting_part_name)

Bases: PartsError

A part name conflicts with another part name because one is nested inside the other.

Parameters:

• part_name (str) – The part name being processed.

• conflicting_part_name (str) – The conflicting part name.

exception craft_parts.errors.PartSpecificationError(*, part_name, message)

Bases: PartsError

A part was not correctly specified.

Parameters:

• part_name (str) – The name of the part being processed.

• message (str) – The error message.

classmethod from_validation_error(*, part_name, error_list)

Create a PartSpecificationError from a pydantic error list.

Parameters:

• part_name (str) – The name of the part being processed.

• error_list (list[ErrorDetails]) – A list of dictionaries containing pydantic error definitions.

Return type:

PartSpecificationError

exception craft_parts.errors.PartitionError(brief, *, details=None, resolution=None)

Bases: PartsError

Errors related to partitions.

Parameters:

• brief (str)

• details (str | None)

• resolution (str | None)

exception craft_parts.errors.PartitionNotFound(partition_name, partitions)

Bases: PartitionUsageError

A partition has been specified that does not exist.

Parameters:

• partition_name (str) – The name of the partition that does not exist.

• partitions (Iterable[str]) – Iterable of the names of valid partitions.

exception craft_parts.errors.PartitionUsageError(error_list, partitions, brief=None)

Bases: PartitionError

Error for a list of invalid partition usages.

Parameters:

• error_list (Iterable[str]) – Iterable of strings describing the invalid usages.

• partitions (Iterable[str] | None) – Iterable of the names of valid partitions.

• brief (str | None) – Override brief message.

exception craft_parts.errors.PartitionUsageWarning(warning_list)

Bases: PartitionError, Warning

Warnings for possibly invalid usages of partitions.

Parameters:

warning_list (Iterable[str]) – Iterable of strings describing the misuses.

exception craft_parts.errors.PartsError(brief, details=None, resolution=None, doc_slug=None)

Bases: Exception

Unexpected error.

Parameters:

• brief (str) – Brief description of error.

• details (str | None) – Detailed information.

• resolution (str | None) – Recommendation, if any.

• doc_slug (str | None) – Reusable documentation slug for consumers adopting the Craft Parts documentation.

property details: str | None

Further details on the error.

exception craft_parts.errors.PluginBuildError(*, part_name, plugin_name, stderr=None)

Bases: UserExecutionError

Plugin build script failed at runtime.

Parameters:

• part_name (str) – The name of the part being processed.

• plugin_name (str) – The name of the plugin being processed.

• stderr (bytes | None) – The contents of the build execution error.

exception craft_parts.errors.PluginCleanError(*, part_name)

Bases: PartsError

Script to clean strict build preparation failed at runtime.

Parameters:

part_name (str) – The name of the part being processed.

exception craft_parts.errors.PluginEnvironmentValidationError(*, part_name, reason)

Bases: PartsError

Plugin environment validation failed at runtime.

Parameters:

• part_name (str) – The name of the part being processed.

• reason (str)

exception craft_parts.errors.PluginNotStrict(plugin_name, *, part_name)

Bases: PartsError

A request was made to use a plugin that’s not strict.

Parameters:

• plugin_name (str) – The plugin name.

• part_name (str) – The name of the part defining the plugin.

exception craft_parts.errors.PluginPullError(*, part_name)

Bases: PartsError

Plugin pull script failed at runtime.

Parameters:

part_name (str) – The name of the part being processed.

exception craft_parts.errors.ScriptletRunError(*, part_name, scriptlet_name, exit_code, stderr=None)

Bases: UserExecutionError

A scriptlet execution failed.

Parameters:

• part_name (str) – The name of the part being processed.

• scriptlet_name (str) – The name of the scriptlet that failed to execute.

• exit_code (int) – The execution error code.

• stderr (bytes | None) – The contents of the scriptlet execution error.

exception craft_parts.errors.StageFilesConflict(*, part_name, conflicting_files)

Bases: PartsError

Files from a part conflict with files already being staged.

Parameters:

• part_name (str) – The name of the part being processed.

• conflicting_files (list[Path]) – The list of confictling files.

exception craft_parts.errors.StagePackageNotFound(*, part_name, package_name)

Bases: PartsError

Failed to install a stage package.

Parameters:

• part_name (str) – The name of the part being processed.

• package_name (str) – The name of the package.

exception craft_parts.errors.UndefinedPlugin(*, part_name)

Bases: PartsError

The part didn’t define a plugin and the part name is not a valid plugin name.

Parameters:

part_name (str) – The name of the part with no plugin definition.

exception craft_parts.errors.UnsupportedBuildAttributesError(unsupported, plugin_name)

Bases: PartsError

Use of build-attributes that a plugin does not support.

Parameters:

• unsupported (set[str])

• plugin_name (str)

exception craft_parts.errors.UserExecutionError(*, brief, resolution, stderr=None)

Bases: PartsError, ABC

Plugin build script failed at runtime.

Parameters:

• part_name – The name of the part being processed.

• plugin_name – The name of the plugin being processed.

• brief (str)

• resolution (str)

• stderr (bytes | None)

property details: str | None

Further details on the error.

Displays the last three trace lines from the error output.

exception craft_parts.errors.XAttributeError(key, path, *, is_write=False)

Bases: PartsError

Failed to read or write an extended attribute.

Parameters:

• action – The action being performed.

• key (str) – The extended attribute key.

• path (Path) – The file path.

• is_write (bool) – Whether this is an attribute write operation.

exception craft_parts.errors.XAttributeTooLong(key, value, path)

Bases: PartsError

Failed to write an extended attribute because key and/or value is too long.

Parameters:

• key (str) – The extended attribute key.

• value (str) – The extended attribute value.

• path (Path) – The file path.

Source handling errors

Exceptions for errors related to source handling are defined in the craft_parts.sources.errors module.

Source handler error definitions.

exception craft_parts.sources.errors.ChecksumMismatch(*, expected, obtained, part_name=None, source=None)

Bases: SourceError

A checksum doesn’t match the expected value.

Parameters:

• expected (str) – The expected checksum.

• obtained (str) – The actual checksum.

• part_name (str | None) – The name of the part being pulled.

• source (str | None) – The source being pulled.

exception craft_parts.sources.errors.HttpRequestError(*, status_code, reason, source)

Bases: SourceError

HTTP error occurred during request processing.

Parameters:

• status_code (int) – Request status code.

• reason (str) – Text explaining status code.

• source (str) – The source defined for the part.

exception craft_parts.sources.errors.IncompatibleSourceOptions(source_type, options)

Bases: SourceError

Source specified options that cannot be used at the same time.

Parameters:

• source_type (str) – The part’s source type.

• options (list[str]) – The list of incompatible source options.

exception craft_parts.sources.errors.InvalidRpmPackage(rpm_file)

Bases: SourceError

An rpm package is invalid.

Parameters:

rpm_file (str) – The filename.

exception craft_parts.sources.errors.InvalidSnapPackage(snap_file)

Bases: SourceError

A snap package is invalid.

Parameters:

snap_file (str) – The snap file name.

exception craft_parts.sources.errors.InvalidSourceOption(*, source_type, option)

Bases: SourceError

A source option is not allowed for the given source type.

Parameters:

• source_type (str) – The part’s source type.

• option (str) – The invalid source option.

exception craft_parts.sources.errors.InvalidSourceOptions(*, source_type, options)

Bases: SourceError

A source option is not allowed for the given source type.

Parameters:

• source_type (str) – The part’s source type.

• options (list[str]) – The invalid source options.

exception craft_parts.sources.errors.InvalidSourceType(source, *, source_type=None)

Bases: SourceError

Failed to determine a source type.

Parameters:

• source (str) – The source defined for the part.

• source_type (str | None)

exception craft_parts.sources.errors.NetworkRequestError(message, *, source=None)

Bases: SourceError

A network request operation failed.

Parameters:

• message (str) – The error message.

• source (str | None) – URL of unreachable source.

exception craft_parts.sources.errors.PullError(*, command, exit_code, resolution=None)

Bases: SourceError

Failed pulling source.

Parameters:

• command (Sequence[str | Path]) – The command used to pull the source.

• exit_code (int) – The command exit code.

• resolution (str | None)

exception craft_parts.sources.errors.SourceError(brief, details=None, resolution=None, doc_slug=None)

Bases: PartsError

Base class for source handler errors.

Parameters:

• brief (str)

• details (str | None)

• resolution (str | None)

• doc_slug (str | None)

exception craft_parts.sources.errors.SourceNotFound(source)

Bases: SourceError

Failed to retrieve a source.

Parameters:

source (str) – The source defined for the part.

exception craft_parts.sources.errors.SourceUpdateUnsupported(name)

Bases: SourceError

The source handler doesn’t support updating.

Parameters:

name (str) – The source type.

exception craft_parts.sources.errors.VCSError(message, resolution=None)

Bases: SourceError

A version control system command failed.

Parameters:

• message (str)

• resolution (str | None)

Package handling errors

Exceptions for errors related to package handling are defined in the craft_parts.packages.errors module.

Exceptions raised by the packages handling subsystem.

exception craft_parts.packages.errors.BaseManifestError(manifest_path, reason)

Bases: PackagesError

Failed to read the base snap package manifest.

Parameters:

• manifest_path (Path) – Path to the manifest file.

• reason (str) – A description of the failure.

exception craft_parts.packages.errors.BuildPackageNotFound(package)

Bases: PackagesError

A package listed in ‘build-packages’ was not found.

Parameters:

package (str) – The name of the missing package.

exception craft_parts.packages.errors.BuildPackagesNotInstalled(*, packages)

Bases: PackagesError

Could not install all requested build packages.

Parameters:

packages (Sequence[str]) – The packages to install.

exception craft_parts.packages.errors.ChiselError(*, slices, output)

Bases: PackagesError

A “chisel”-related command failed.

Parameters:

• slices (list[str])

• output (str)

exception craft_parts.packages.errors.DebPackageInvalidFormatError(package)

Bases: PackagesError

The given package specification is not formatted correctly.

Parameters:

package (str) – The package specification string.

exception craft_parts.packages.errors.FileProviderNotFound(*, file_path)

Bases: PackagesError

A file is not provided by any package.

Parameters:

file_path (str) – The file path.

exception craft_parts.packages.errors.PackageBackendNotSupported(backend)

Bases: PartsError

Requested package resolved not supported on this host.

Parameters:

backend (str)

exception craft_parts.packages.errors.PackageBroken(package_name, *, deps)

Bases: PackagesError

Package has unmet dependencies.

Parameters:

• package_name (str) – The name of the package with unmet dependencies.

• deps (Sequence[str]) – The list of unmet dependencies.

exception craft_parts.packages.errors.PackageFetchError(url, details=None)

Bases: PackagesError

Failed to fetch package from remote repository.

Parameters:

• url (str | None) – The package URL, if known.

• details (str | None) – Additional error details from the underlying exception.

exception craft_parts.packages.errors.PackageListRefreshError(message)

Bases: PackagesError

Failed to refresh the list of available packages.

Parameters:

message (str) – The error message.

exception craft_parts.packages.errors.PackageNotFound(package_name)

Bases: PackagesError

Requested package doesn’t exist in the remote repository.

Parameters:

package_name (str) – The name of the missing package.

exception craft_parts.packages.errors.PackagesDownloadError(*, packages)

Bases: PackagesError

Failed to download packages from remote repository.

Parameters:

packages (Sequence[str]) – The packages to download.

exception craft_parts.packages.errors.PackagesError(brief, details=None, resolution=None, doc_slug=None)

Bases: PartsError

Base class for package handler errors.

Parameters:

• brief (str)

• details (str | None)

• resolution (str | None)

• doc_slug (str | None)

exception craft_parts.packages.errors.PackagesNotFound(packages)

Bases: PackagesError

Requested package doesn’t exist in the remote repository.

Parameters:

• package_name – The names of the missing packages.

• packages (Sequence[str])

exception craft_parts.packages.errors.SnapDownloadError(*, snap_name, snap_channel)

Bases: PackagesError

Failed to download a snap.

Parameters:

• snap_name (str) – The snap name.

• snap_channel (str) – The snap channel.

exception craft_parts.packages.errors.SnapGetAssertionError(*, assertion_params)

Bases: PackagesError

Failed to retrieve snap assertion.

Parameters:

assertion_params (Sequence[str]) – The snap assertion parameters.

exception craft_parts.packages.errors.SnapInstallError(*, snap_name, snap_channel)

Bases: PackagesError

Failed to install a snap.

Parameters:

• snap_name (str) – The snap name.

• snap_channel (str) – The snap channel.

exception craft_parts.packages.errors.SnapInvalidFormat(snap)

Bases: PackagesError

The given snap specification is not formatted correctly.

Parameters:

snap (str) – The snap specification string.

exception craft_parts.packages.errors.SnapRefreshError(*, snap_name, snap_channel)

Bases: PackagesError

Failed to refresh a snap.

Parameters:

• snap_name (str) – The snap name.

• snap_channel (str) – The snap channel.

exception craft_parts.packages.errors.SnapUnavailable(*, snap_name, snap_channel)

Bases: PackagesError

Failed to install or refresh a snap.

Parameters:

• snap_name (str) – The snap name.

• snap_channel (str) – The snap channel.

exception craft_parts.packages.errors.SnapdConnectionError(*, snap_name, url)

Bases: PackagesError

Failed to connect to snapd.

Parameters:

• snap_name (str) – The snap name.

• url (str) – The failed connection URL.

exception craft_parts.packages.errors.UnpackError(package)

Bases: PackagesError

Error unpacking stage package.

Parameters:

package (str) – The package that failed to unpack.