OpenKeel: the sovereign French Cloud solution of the inherent group, with a European reach Discover inherent

Reverse-spec · Services

magnum — Errors

Errors — magnum — branch stable/2026.2

Branch stable/2026.2 @ 1910928b7d9f — repository https://opendev.org/openstack/magnum — analysed on 2026-11-09

All Magnum errors derive from MagnumException (magnum/common/exception.py:70). Each class has a message template, formatted with the constructor's keyword arguments, and a code, which is the HTTP status (500 by default). If the arguments do not match the template, the unformatted template is used and the failure is logged (magnum/common/exception.py:90). Passing message= replaces the template entirely (magnum/common/exception.py:87). The full class list, with inheritance, is in [_inventory/inventory_stable-2026.2.md](_inventory/inventory_stable-2026.2.md) § "Exceptions Python".

Exception → HTTP translation

There is no central translation table. Translation happens in three layers:

  1. WSME (@expose = wsme_pecan.wsexpose, JSON only, magnum/api/expose.py:14) catches every exception raised by a handler and sets the HTTP status from the exception's code attribute. wsme.exc.ClientSideError is a 400. Any other exception, i.e. an attribute error, a KeyError or an untranslated library exception, is a 500. WSME produces {"faultcode": "Client"|"Server", "faultstring": "<message>", "debuginfo": null}.
  2. **NoExceptionTracebackHook** cuts any remote traceback out of faultstring (magnum/api/hooks.py:84). An exception re-raised from the conductor through an RPC call carries its traceback in the message.
  3. **ParsableErrorMiddleware** rewrites every response with status ≥ 400 into the final body (magnum/api/middleware/parsable_error.py:56): json {"errors": [{"request_id": "", "code": "client", "status": 404, "title": "Cluster k8s-prod could not be found", "detail": "Cluster k8s-prod could not be found.", "links": []}]} title is the text up to the first . of faultstring. code is the lower-cased WSME faultcode (client or server). request_id is always empty, so the request ID is only available in the X-Openstack-Request-Id header (oslo.middleware RequestId, etc/magnum/api-paste.ini:8).

Microversion errors bypass WSME. HTTPNotAcceptableAPIVersion builds its own body, with code = "magnum.microversion-unsupported", title = "Requested microversion is unsupported", min_version, max_version and a help link (magnum/api/http_error.py:59).

Errors from RPC calls: for the routes that use an RPC call (upgrade, certificates, credential rotation, all database access through the indirection API when magnum-api is the binary), the conductor's exception is rebuilt in the API as a <Class>_Remote subclass that keeps code and message (magnum/common/exception.py:114). The client gets the same status as if the exception had been raised locally. A timeout (oslo_messaging.MessagingTimeout) has no code and becomes a 500.

Errors from RPC casts (create, update, delete, resize, nodegroups) never reach the client: they become a resource status (*_FAILED + status_reason) or only a log line (see § Asynchronous errors).

Status overrides: two places change the code of an exception on the fly.

  • ClusterTemplateNotFound becomes 400 on POST /v1/clusters at microversions 1.1–1.9 (magnum/api/validation.py:45).
  • ClusterNotFound becomes 400 when a certificate is posted for an unknown cluster (magnum/api/controllers/v1/certificate.py:69).

Some classes also declare a code that does not match their parent. ImageNotFound, FlavorNotFound, FixedNetworkNotFound, FixedSubnetNotFound, ExternalNetworkNotFound, VolumeTypeNotFound and OSDistroFieldNotFound are ResourceNotFound subclasses with 400 (magnum/common/exception.py:294–magnum/common/exception.py:367): a missing dependency in the request is a bad request, not a missing route resource.

Catalogue (synchronous errors, seen as HTTP statuses)

ExceptionHTTPMessage (template)SituationRaised atSeen by the client as
(keystonemiddleware)401Authentication requiredmissing, invalid or expired token on any route except /, /v1 and /healthcheckmagnum/api/middleware/auth_token.py:60401 + WWW-Authenticate
HTTPNotAcceptable406"Invalid service type for OpenStack-API-Version header"header without a space, or service not one of container-infra, container-infrastructure, container-infrastructure-managementmagnum/api/controllers/versions.py:104, magnum/api/controllers/versions.py:111WSME-less 406
HTTPNotAcceptable406"Invalid value for OpenStack-API-Version header"version not X.Ymagnum/api/controllers/versions.py:119406
HTTPNotAcceptableAPIVersion406"Version %(ver)s was requested but the minor version is not supported by this service…"requested version outside 1.1–1.14, or major ≠ 1magnum/api/controllers/v1/__init__.py:204, magnum/api/controllers/v1/__init__.py:216406, code: magnum.microversion-unsupported
HTTPNotAcceptable406"Version %(ver)s was requested but the requested API %(api)s is not supported for this version."route exists but not at the requested microversion (nodegroups < 1.9, resize < 1.7, credentials < 1.12)magnum/api/controllers/base.py:113406
PolicyNotAuthorized403"Policy doesn't allow %(action)s to be performed."a policy rule refused the action, or the token has an invalid scopemagnum/common/policy.py:102, magnum/common/policy.py:106403
NotAuthorized403"Not authorized."non-admin uses a hidden template (magnum/api/controllers/v1/cluster.py:535); non-admin reads another project's quota (magnum/api/controllers/v1/quota.py:161) or stats (magnum/api/controllers/v1/stats.py:69)see situation403
ClusterTemplatePublishDenied403"Not authorized to set public or hidden flag for cluster template."non-admin creates or patches a template with public/hiddenmagnum/api/controllers/v1/cluster_template.py:437, magnum/api/controllers/v1/cluster_template.py:519403
ResourceLimitExceeded403"Resource limit exceeded: You have reached the maximum clusters per project, %d. You may delete a cluster to make room for a new one."the project already has ≥ its cluster quotamagnum/api/controllers/v1/cluster.py:500403
ImageNotAuthorized403"Not authorized for image %(image_id)s."Glance returns 403 for the template imagemagnum/api/attr_validator.py:44, magnum/api/validation.py:84403
ClusterNotFound404"Cluster %(cluster)s could not be found."unknown cluster UUID or name, or a cluster of another projectmagnum/db/sqlalchemy/api.py:195, magnum/db/sqlalchemy/api.py:209, magnum/db/sqlalchemy/api.py:219404 (400 on POST /v1/certificates)
ClusterTemplateNotFound404"ClusterTemplate %(clustertemplate)s could not be found."unknown template, a private template of another project, or a hidden template seen by a non-admin of another projectmagnum/db/sqlalchemy/api.py:347, magnum/db/sqlalchemy/api.py:390, magnum/api/controllers/v1/cluster_template.py:391404 (400 on POST /v1/clusters < 1.10)
NodeGroupNotFound404"Nodegroup %(nodegroup)s could not be found."unknown nodegroup in the clustermagnum/db/sqlalchemy/api.py:908, magnum/db/sqlalchemy/api.py:920, magnum/db/sqlalchemy/api.py:937404
FederationNotFound404"Federation %(federation)s could not be found."unknown federationmagnum/db/sqlalchemy/api.py:747, magnum/db/sqlalchemy/api.py:772404
QuotaNotFound404"Quota could not be found: %(msg)s"PATCH/DELETE of a quota without an explicit rowmagnum/db/sqlalchemy/api.py:663, magnum/db/sqlalchemy/api.py:681404 (GET synthesises a default instead)
ProjectNotFound404"The %(name)s %(id)s could not be found."POST /v1/quotas for a project unknown to Keystonemagnum/api/validation.py:150404
HTTPNotFound404"The %(name)s resource %(id)s could not be found." / free text/detail reached under a wrong parent (magnum/api/controllers/v1/cluster.py:433); unjoin of a non-member cluster (magnum/api/controllers/v1/federation.py:432)see situation404
Conflict409"Multiple clusters exist with same name. Please use the cluster uuid instead." (and the same for templates, federations, nodegroups)a name matches several rowsmagnum/db/sqlalchemy/api.py:205, magnum/db/sqlalchemy/api.py:385, magnum/db/sqlalchemy/api.py:767, magnum/db/sqlalchemy/api.py:932409
Conflict409"Multiple images exist with name %s…" / networks / subnetsGlance or Neutron name lookup is ambiguousmagnum/api/attr_validator.py:42, magnum/api/attr_validator.py:96, magnum/api/attr_validator.py:116, magnum/api/attr_validator.py:138409
ClusterTemplateAlreadyExists409"A ClusterTemplate with UUID %(uuid)s already exists."duplicate UUIDmagnum/db/sqlalchemy/api.py:327409
QuotaAlreadyExists409"Quota for project %(project_id)s already exists for resource %(resource)s."second POST /v1/quotas for the same project and resourcemagnum/db/sqlalchemy/api.py:625409
NodeGroupAlreadyExists409"A node group with name %(name)s already exists in the cluster %(cluster_id)s."name reused in the cluster (API check, then unique constraint)magnum/api/controllers/v1/nodegroup.py:466, magnum/db/sqlalchemy/api.py:865409 (API); conductor log (DB)
NodeGroupInvalidInput409"%(attr)s for %(nodegroup)s is invalid (%(expl)s)."min > node_count, node_count > max, min > max, restricted label, bad taint, labels/taints on mastermagnum/api/controllers/v1/nodegroup.py:98–magnum/api/controllers/v1/nodegroup.py:176409, although these are input errors
ClusterAPIAddressUnavailable409"Cluster API address is not available yet"nodegroup created before the cluster has an API addressmagnum/api/controllers/v1/nodegroup.py:463409
InvalidClusterTemplateForUpgrade409"Cluster Template is not valid for upgrade: %(reason)s"upgrade of a non-default nodegroup to a template other than the cluster'smagnum/api/controllers/v1/cluster_actions.py:187409
MemberAlreadyExists409"A cluster with UUID %(uuid)s is already a member of the federation %(federation_name)s."join of a member clustermagnum/api/controllers/v1/federation.py:395409
InvalidParameterValue400"%(err)s"invalid patch property (magnum/api/validation.py:270), unsupported COE / network / volume driver / server type (magnum/api/validation.py:289–magnum/api/validation.py:343), devicemapper volume < 3 GB (magnum/api/validation.py:258), master_count > 1 without master_lb_enabled (magnum/api/attr_validator.py:177), stats type (magnum/api/controllers/v1/stats.py:60), quota without project (magnum/api/controllers/v1/quota.py:188), unknown sort key (magnum/db/sqlalchemy/api.py:98), UUID overwrite (magnum/db/sqlalchemy/api.py:262, magnum/db/sqlalchemy/api.py:431), federation host cluster / dns-zone (magnum/api/attr_validator.py:214, magnum/api/attr_validator.py:227)see situation400
PatchError400"Couldn't apply patch '%(patch)s'. Reason: %(reason)s"JSON Patch cannot be applied (bad path, wrong type), or ast.literal_eval failed on a labels stringmagnum/api/controllers/v1/cluster.py:692, magnum/api/controllers/v1/cluster_template.py:509, magnum/api/controllers/v1/nodegroup.py:549, magnum/api/utils.py:95400
wsme.exc.ClientSideError400"Limit must be positive" / "Invalid sort direction…" / "Adding a new attribute %s to the root of the resource is not allowed." / "The attribute %s has existed, please use 'replace' operation instead." / non-removable or internal attributelist parameters and JSON Patch rulesmagnum/api/utils.py:41, magnum/api/utils.py:51, magnum/api/utils.py:79, magnum/api/utils.py:83, magnum/api/controllers/v1/types.py:205400
InvalidName / InvalidUUID / InvalidIdentity400"Expected a name but received %(name)s." …malformed identifiermagnum/api/controllers/v1/types.py:65, magnum/db/sqlalchemy/api.py:86, magnum/objects/cluster.py:208400
InvalidDNS400"Expected a single dns address or comma separated dns list, but received %(dns)s."bad dns_nameservermagnum/common/utils.py:138400
ZeroNodeCountNotSupported400"Resizing a nodegroup to zero is not supported in the provided microversion."node_count 0 below 1.10magnum/api/controllers/v1/cluster.py:510, magnum/api/controllers/v1/cluster.py:627, magnum/api/controllers/v1/cluster_actions.py:90400
ClusterUpgradeNotSupported400"Cluster upgrade is not supported in the provided microversion."upgrade at 1.7magnum/api/controllers/v1/cluster_actions.py:147400
NGResizeOutBounds400"Resizing %(nodegroup)s outside the allowed range: min_node_count = %(min_nc)s, max_node_count = %(max_nc)s"resize outside the nodegroup boundsmagnum/api/controllers/v1/cluster_actions.py:122, magnum/api/controllers/v1/cluster_actions.py:127400
MasterNGSizeInvalid400"master nodegroup size of %(requested_size)s is invalid, size cannot be an even number."even or < 1 master_count (base driver rule)magnum/drivers/common/driver.py:255400
MasterNGResizeNotSupported400"Resizing the master nodegroup is not supported by this driver."resize of the master nodegroup with a driver that keeps the base rulemagnum/drivers/common/driver.py:260400
CreateMasterNodeGroup400"Creating master nodegroups is currently not supported."role=master on nodegroup createmagnum/api/controllers/v1/nodegroup.py:476400
DeletingDefaultNGNotSupported400"Deleting a default nodegroup is not supported."delete of default-master/default-workermagnum/api/controllers/v1/nodegroup.py:536400
ClusterTemplateReferenced400"ClusterTemplate %(clustertemplate)s is referenced by one or multiple clusters."delete, or change other than name/public/hidden, of a template used by a clustermagnum/db/sqlalchemy/api.py:422, magnum/db/sqlalchemy/api.py:451400
ClusterTypeNotSupported400"Cluster type (%(server_type)s, %(os)s, %(coe)s) is not supported by any loaded cluster driver. Loaded drivers support: %(supported_cluster_types)s."no installed driver provides the template's tuple (with no driver at all: "none (no cluster drivers are loaded)")magnum/drivers/common/driver.py:141400
ClusterTypeBetaNotEnabled400"Cluster type (…) is provided by the '%(driver_name)s' driver, which is a beta driver and is not enabled…"beta driver not listed in [drivers]/enabled_beta_driversmagnum/drivers/common/driver.py:154400
ClusterDriverNotSupported400"Cluster driver (%(driver_name)s) not supported."template driver, image magnum_driver or [drivers]/default_driver names an uninstalled drivermagnum/drivers/common/driver.py:134, magnum/drivers/common/driver.py:181400
ImageNotFound400"Image %(image_id)s could not be found."template image missing in Glancemagnum/api/attr_validator.py:38, magnum/api/validation.py:82400
OSDistroFieldNotFound400"Image %(image_id)s doesn't contain os_distro field."image without os_distromagnum/api/attr_validator.py:46, magnum/api/validation.py:88400
FlavorNotFound400"Unable to find flavor %(flavor)s."flavor not in Nova's listmagnum/api/attr_validator.py:63, magnum/api/attr_validator.py:198400
FlavorZeroRootVolumeNotSupported400"Flavor with zero root volume size is not supported when boot_volume_size is zero."boot_volume_size 0 and flavor disk 0magnum/api/attr_validator.py:201400
KeyPairNotFound404"Unable to find keypair %(keypair)s."Nova keypair missing (unlike the other missing dependencies, which are 400)magnum/api/attr_validator.py:76404
ExternalNetworkNotFound / FixedNetworkNotFound / FixedSubnetNotFound400"Unable to find external network %(network)s." …Neutron resource missing (or not router:external)magnum/api/attr_validator.py:91, magnum/api/attr_validator.py:112, magnum/api/attr_validator.py:134400
NotSupported400"%(operation)s is not supported."CA rotation on a non-TLS cluster (magnum/api/controllers/v1/certificate.py:188); via RPC call: upgrade/rotation/credential in a wrong status (magnum/conductor/handlers/cluster_conductor.py:287, magnum/conductor/handlers/ca_conductor.py:89, magnum/conductor/handlers/credential_conductor.py:50), driver without CA rotation (magnum/drivers/common/driver.py:307) or credential rotation (magnum/conductor/handlers/credential_conductor.py:57)see situation400
InvalidCsr400"Received invalid csr %(csr)s."CSR cannot be parsedmagnum/common/x509/operations.py:200400
CertificateValidationError400"Extension '%(extension)s' not allowed"CSR asks for a forbidden extension, key usage or CA basic constraintmagnum/common/x509/validator.py:64, magnum/common/x509/validator.py:83, magnum/common/x509/validator.py:105400
AuthorizationFailure403"%(client)s connection failed. %(message)s"Keystone client without token or password (magnum/common/keystone.py:79); any keystoneauth/openstacksdk error in a wrapped callmagnum/common/exception.py:59403
RegionsListFailed500"Failed to list regions."Keystone region listing fails while validating [*]/region_namemagnum/common/keystone.py:105500
CertificatesToClusterFailed500"Failed to create certificates for Cluster: %(cluster_uuid)s"CA generation or storage fails (Barbican down, local path not writable)magnum/conductor/handlers/common/cert_manager.py:128async: CREATE_FAILED; via CA rotation call: 500
CertificateStorageException500"Could not store certificate: %(msg)s"local cert manager I/O errormagnum/common/cert_manager/local_cert_manager.py:102500 / CREATE_FAILED
AttributeError (not a Magnum class)500"'ClusterTemplatesController' object has no attribute '_coreos_deprecation_note'"template created with coe=kubernetes and an image whose os_distro is coreosmagnum/api/controllers/v1/cluster_template.py:462500
MessagingTimeout500oslo.messaging textno conductor answered an RPC call within rpc_response_timeout (upgrade, certificates, credentials, indirection)magnum/conductor/api.py:84, magnum/conductor/api.py:125–magnum/conductor/api.py:134, magnum/conductor/api.py:141500
DBConnectionError and other oslo.db errors500oslo.db textdatabase unreachableany magnum/db/sqlalchemy/api.py session500

Defined but never raised in this branch (dead code kept for the driver API or for history): InvalidDiscoveryURL, GetDiscoveryUrlFailed, InvalidClusterDiscoveryURL, InvalidClusterSize, GetClusterSizeFailed, InvalidCsr is raised (above); InvalidSubnet, InvalidVersion, ApiVersionsIntersect (only at import time, magnum/api/controllers/base.py:184), ClusterAlreadyExists (raised only from a conductor insert, magnum/db/sqlalchemy/api.py:184), RequiredParameterNotProvided, OperationInProgress, NgOperationInProgress, X509KeyPair*, MagnumService*, ServicesListFailed (magnum/common/keystone.py:137, only used by drivers), PreDeletionFailed (magnum/common/neutron.py:52, magnum/common/octavia.py:101, helpers for drivers), VolumeTypeNotFound (magnum/common/cinder.py:46, driver helper), UnsupportedK8sQuantityFormat (magnum/common/utils.py:227, monitor helper), ObjectError, ConfigInvalid (startup only, magnum/api/middleware/auth_token.py:44). Drivers may raise any of these; see 08.

Asynchronous errors

WhereWhat happensWhat the user seesWhere the operator looks
cluster_create fails after the row insert (certificates, driver)cluster.status = CREATE_FAILED, status_reason = str(e), CADF magnum.cluster.create failure (magnum/conductor/handlers/cluster_conductor.py:77)GET shows CREATE_FAILED and the reason; faults lists failed nodegroupsconductor log (exception re-raised), notification error
cluster_create fails before the row insert (duplicate UUID, database down)exception logged, nothing storedthe UUID from the 202 returns 404 foreverconductor log only
cluster_update refused (status not *_COMPLETE)NotSupported raised in the cast, CADF update failure (magnum/conductor/handlers/cluster_conductor.py:104)202 then nothing: the size does not changeconductor log, notification
cluster_update / cluster_resize / cluster_upgrade driver errorcluster UPDATE_FAILED + reason; nodegroup size restored (update, resize) or nodegroup UPDATE_FAILED (resize, upgrade)UPDATE_FAILEDconductor log, notification
cluster_resize refused (status)NotSupported in the cast202 then nothingconductor log
cluster_delete driver errorDELETE_FAILED + reasonDELETE_FAILED; retry DELETEconductor log, notification
nodegroup create / update / delete driver errornodegroup CREATE_FAILED / UPDATE_FAILED / DELETE_FAILED + reason; cluster UPDATE_FAILED (magnum/conductor/handlers/nodegroup_conductor.py:85, magnum/conductor/handlers/nodegroup_conductor.py:106, magnum/conductor/handlers/nodegroup_conductor.py:126)nodegroup and cluster statusesconductor log (no notification)
nodegroup operation refused by allowed_operationNotSupported in the cast; message shows the cluster status, not the nodegroup's202 then nothingconductor log
federation create / update / deleteNotImplementedError in the cast202 then nothing (create: the federation never exists)conductor log
sync_cluster_status driver errorlooping call stopped, logged "Ignore error [%s] when syncing up cluster status." or raised from the job; retried 10 s laterstatus frozenconductor log (warning)
status poller sees DELETE_COMPLETE but certificate deletion failswarning "Deleting certs is failed for Cluster %s", row still removed (magnum/conductor/handlers/common/cert_manager.py:247)cluster goneconductor log; secrets left in Barbican
health poll failswarning "Skip pulling data from cluster %(cluster)s due to error: %(e)s", previous health kept (magnum/service/periodic.py:112)stale health_statusconductor log
health poll on a cluster without a public APIhealth_status = UNKNOWN, reason {"api": "The cluster <name> is not accessible."} (magnum/drivers/common/k8s_monitor.py:57)UNKNOWN—

Key log messages

LevelMessageSituationDefined at
ERRORConfigured [drivers] default_driver %r is not a registered driver. Available drivers: %stemplate created while [drivers]/default_driver names a missing drivermagnum/drivers/common/driver.py:177
WARNINGNo Magnum drivers are available and [drivers] default_driver is not configured.no driver package installedmagnum/drivers/common/driver.py:187
INFODriver {driver_name} is beta and needs to be explicitly enabled with [drivers]/enabled_beta_drivers.beta driver selectedmagnum/drivers/common/driver.py:151
ERROR (exception)Failed to generate certificates for Cluster: %sCA generation or storage failed during create or rotationmagnum/conductor/handlers/common/cert_manager.py:126
ERROR (exception)Error storing certificate data / Error getting %sBarbican errormagnum/common/cert_manager/barbican_cert_manager.py:167, magnum/common/cert_manager/barbican_cert_manager.py:192
WARNINGIgnore error [%s] when syncing up cluster status.exception in a periodic taskmagnum/service/periodic.py:182, magnum/service/periodic.py:217
WARNINGSkip pulling data from cluster %(cluster)s due to error: %(e)shealth monitor failuremagnum/service/periodic.py:112
WARNINGDeleting certs is failed for Cluster %scertificate cleanup failuremagnum/conductor/handlers/common/cert_manager.py:247
WARNINGin-tree Cinder driver / devicemapper / overlay deprecation notesdeprecated template or cluster optionsmagnum/api/controllers/v1/cluster.py:559, magnum/api/controllers/v1/cluster_template.py:458
ERROR (exception)Exception in string format operation, kwargs: %sexception arguments do not match the templatemagnum/common/exception.py:95
ERROR (exception)Failed to list regionsKeystone region list failedmagnum/common/keystone.py:104
DEBUGProcessing request: url: %(url)s, %(method)s, body: %(body)severy v1 request with a body — logs request bodies, including CSRs and labels, at DEBUGmagnum/api/controllers/v1/__init__.py:241

Source: reverse-spec-magnum/02-errors_stable-2026.2.md. The _rewrite/ and _inventory/ files are not published on the site.