The kernel reports problems at four levels: the call itself can fail (a trap), the request can be refused (an error reply), the request can run and report a failure in its result, and a regen can run and report failures per feature. This chapter describes each level, how hints are attached, and lists the codes that the kernel can emit.
The call to ck_request throws a WebAssembly.RuntimeError; ck_panic got the text first. The instance is unusable; the host starts a new one (Call it from Node). The native service, when built with the service profile, answers HTTP 500 and closes the session (a release build aborts the process instead).
an internal panic
Error reply
{"ok": false, "error": "<message>", "ms": ...}. error is always a string.
noState: nothing regenerated yet
Failure in the result
ok is true; the result says the operation failed.
{"error": "notFound"}, an issues list, an import with body: null
Feature error
ok is true; the regen result has errors (and warnings) with one entry per failed feature.
["F4", {"code": "holeInvalid", ...}]
The first rule of thumb: ok: false means the request was not carried out and nothing changed. A regen with failed features is not a failed request: ok is true, the tag is replaced with the partial result, and the failures are data.
There is no msg key, or it is not an object (a top-level array or string gives the same).
message without a type
msg.type is missing, empty or not a string.
unknown request <type>
No such request type; the type is echoed as sent.
noState: nothing regenerated yet
A request that needs a tag was sent for a tag that has no state. Clients match on the prefix noState.
invalid part: Format
regen, matchEdges, refDiff or checkProfile/sketchAnalyze/sketchFreedoms with a part that is not a part document (not an object, wrong format, or features not an array). The tag keeps its state.
face is not a string, or point / target is not a triple of numbers.
bad sketch frame
convert
frame is not an object with numeric triples o, x, y, z.
sketchOffset without a distance
sketchOffset
distance is missing or not a number.
drawing: a view needs a name (front, back, left, right, top, bottom, iso) or x and y
drawing
A view has neither a known name nor both x and y.
massProps: densities has N entries but the body has M lump(s) (expected M)
massProps
densities does not have one entry per lump.
importStep: data must be a STEP file as a string, importSat: data (the SAT file text) is required, importSldprt: data (the .SLDPRT file as base64) is required, importSkp: data (the .skp file as base64) is required
imports
data is missing.
importSkp: opts.up must be "z", "y" or "yFlip", got ...
importSkp
Unknown opts.up.
cannot inspect nothing, cannot inspect <kind>, <kind> not found, vertex without a point, no vertex
A bad or missing argument, named after the request: angles: edges ('all' | [keys]), faces [a, b] or draft {pull} is required, closestPoint: at most 2000 points per request, closestPoint: on must be 'body', 'face', 'edge' or 'vertex', extrema: dir must not be zero, probe: at most 2000 points per request (and rays), probe: points [[x, y, z], ...] or rays [{origin, dir}, ...] is required, probe: ray.dir must not be zero, section: plane.normal must not be zero, sections: axis must be 'x', 'y', 'z' or [nx, ny, nz], sections: between 1 and 1000 positions, symmetry: plane.normal must not be zero, thickness: the body has no faces, thicknessAt: point [x, y, z] or face id is required, clearance: more than 4000 faces, maxDistance: nothing to sample. Entity arguments that cannot be read give unknown entity ..., no lump N (the body has M) or expected a face / edge / vertex id, a point, a lump or ....
dfmMinWall: threshold must be a positive number (and the like)
dfm*
The required limit is missing or out of range; the message starts with the request name.
Unknown profile, rule or parameter, a wrong type or a value out of range; the message lists the valid choices.
sketchAnalyze: featureId must be a string, sketchAnalyze: sketch F9 not found (and sketchFreedoms: ...)
sketch analysis
Missing or unknown featureId.
textBadHeight: ..., textEmpty, textFontNotLoaded: font "x" is not loaded; ..., fontBadData: ..., fontBadName, fontReserved, fontNameConflict, fontTooLarge, fontTooMany, fontSubsetFailed: ...
The body is not one the rule can judge: emptyBody, nonAnalyticFaces, tessellationFailed.
body: null and an errors entry
imports
The file could not be read. The entry is ["import", { "code", "params" }] for every importer (codes such as parse, container.magic, container.format, sat.parse). See Import and export.
Each failed feature has one entry in errors: [featureId, { "code": "<code>", "params": { ... } }]. If a feature has no id, the id is the empty string. An id appears once; a later entry for the same feature replaces an earlier one. A failed feature changes nothing: the body is as it was before the feature, and later features run on it.
params is an object that depends on the code. These conventions apply to many codes:
hint: one sentence on what to change. Present on the codes whose cause the kernel can name (holeInvalid, booleanFailed, invalidValue for a scale factor, threadSizeUnknown, the loft codes, …). Show it first when reporting the failure.
detail: a sentence naming the faces or edges involved, often with numbers: F3.B0: spring leaves its face away from its edges.
field: for invalidValue and missingReference, which field of the feature is wrong (thin.thickness, regions, endRef).
Numbers that say how far off the request was: max (largest blend radius that fits), limit, minRadius, maxThickness, maxHeight, budgetMs, elapsedMs.
maxSize: { "param", "value", "unit" } on a refusal because a size is too large: param is the feature field (a dotted path for a nested one, thin.thickness), value the largest value of it that builds (the sign of the request kept, so a face pushed in by -12 gets -9.96), unitmm or deg. The hint says the same in words. Given only for a value the kernel built with its own checks (or the exact bound of a closed-form check), so a client can set the field to it without parsing text; when no such value is found it is absent. Given today by shell (thickness), moveFace (distance), draft (angle), a drafted extrude (draft), a thin wall (thin.thickness), hole (cboreDepth, cskDiameter) and knurlBand (depth); not yet by fillet and chamfer.
name and nearest: for a body or face name that does not resolve, with up to three existing names that are close.
ref, candidates, hint: for a face id that no face carries (missingReference from shell, thread, combine, deleteFace, moveBody, pipeCut, fullRound, the surface features and projectCurve). candidates lists up to six live face ids, those of the same feature first and the closest name first, or the three closest names of the whole model when the feature has no face left; hint says which of the two it is. A repair is a one-field edit: replace ref by one of candidates.
faces, gone, candidates, neighbours, hint: for missingEdge on an edge pick {faces, at} that no edge joins any more. gone lists the names no face carries (with candidates as above); when both faces exist, neighbours lists the faces the first one now meets.
Because a failure removes a feature’s output, the next features that depend on it fail too. The errors are in feature id order as strings, but the cause is the first failing feature in document order.
featureBudgetExceeded and regenBudgetExceeded report that a time limit stopped the work. When the limit of a feature (opts.featureTimeMs, default two minutes) has run out, a feature that failed at that moment reports featureBudgetExceeded instead of its own code, unless its own code already ends in BudgetExceeded (a boolean stopped by the limit keeps booleanBudgetExceeded); its result is not applied. When the limit of the whole document (opts.regenTimeMs) has run out, the running feature and every later one report regenBudgetExceeded; the later ones are not run. The params are budgetMs, elapsedMs, hint and, if the feature had failed for another reason, cause (that code). A feature limit that has already passed when a feature starts (a few microseconds, for instance) is reported as regenBudgetExceeded with the feature limit’s hint. Budgets need a host clock (Protocol overview).
Budget failures are not cached. A failure caused by a time budget is not stored in the regen cache, so a later regen of the same part runs again with its own budget. Builds before this change replayed the stored error (and body: null) on the same instance; opts.noCache: true was the workaround.
The feature’s type is not a known type. params.type is the type as given (empty if missing).
missingReference
A reference does not resolve: a face, edge, plane, axis or body name that does not exist, a required reference field that is absent, or a feature that needs a body when there is none. Often has field, face, ref or name and nearest.
missingSketch
The feature’s sketch is absent or names no sketch that was regenerated before it (also when that sketch failed).
badExpression
A numeric field or constraint value is an expression that does not evaluate: syntax error, unknown name or function, or a variable that is itself invalid or part of a cycle.
invalidValue
A value is out of range or the wrong shape: a radius, count, angle, factor or distance that must be positive, an unknown option value, a mix of options that does not work together. params has detail, field or hint.
noClosedProfile
The sketch has no closed profile to build from. sketchAnalyze says why.
nothingToCut
The feature modifies a body (cut, shell, rib, draft, mate, …) but the document has no body yet.
noBodies
deleteBody with no body in the document.
noFaces
moveFace, pressPull, or draft with a valid neutral plane, was given an empty faces list.
noSeeds
A pattern or mirror has an empty seeds list or nothing to copy.
unsupported
An option of a fillet or chamfer that the kernel does not build. params.what names it (chamfer <type>, fillet profile <name>, fillet <filletType>). Any filletType is refused this way, including "circular": filletType: "circular" gives unsupported { what: "fillet circular" } although circular is also the name of the default profile. Leave filletType out, or use "fullRound".
TODO(rebuild): <what> needs ck-ops
The feature type is accepted but not implemented (see Regeneration), or the particular option is refused. The code is this whole sentence.
healed
Not an error. With autoHeal, the feature’s body had validation issues and was repaired; params has fixed, codes and remaining. It is listed in errors.
The variable table of the part (variables) is resolved before the features run. A variable with an invalid name, one that depends on a cycle, and one whose expression does not evaluate are all left unset in the reply, so no code of their own is reported; the features that use them fail with badExpression.
regions matched no closed region of the sketch (an empty list, or ids that are no region’s outer boundary). It never falls back to “all regions”. params.regions lists them.
extrudeRegionUnknown
regions names ids that are no entity of the sketch. params.ids.
unknownEnd
The end condition is not a known one. params.end.
upToFaceBehind, upToPointBehind
The end face (or the plane through the end point) is not ahead of the whole profile in the extrusion direction, or is parallel to it.
upToFaceOutside
upToFace: the face does not cover the whole profile along the direction. params.face.
upToFaceUnsupported
The end face is not planar. params.face.
endClipFailed
The boolean that trims a slanted end failed. By default it appears only as the reason of an endConditionFallback warning; with strictEnd: true it is the error. params.detail.
upToNextNone
upToNext cut: no face to stop at.
upToNextOpen
upToNext add: the tool never meets the body.
missingAxis
A revolve has no axis, or its axis does not resolve to a line of the sketch.
profileCrossesAxis
A revolve profile straddles the axis. params.detail.
thinTooThick
A thin-wall extrude or revolve: the thickness is too large for the profile (a corner or curvature limit). params: limit (curvature or corner), minRadius, maxThickness, thickness, face.
offsetFitFailed
The offset curve of a thin-wall profile could not be fitted within tolerance.
zeroDepth
An extrusion or twisted extrusion with no depth (below 1e-9). The extrude feature itself replaces a depth of zero or less by 1e-6, so this code shows only on paths that do not; the extrude feature raises the warning extrudeZeroDepth instead (see Warnings).
A revolve with a zero angle, an axis that is not in the sketch plane, or a profile that is degenerate about the axis.
draftTooLarge
A drafted extrude: the taper closes to a point, or an edge turns over. params.detail; for an extrude of one circle params.maxHeight is the greatest depth that works.
draftUnsupported
A twisted extrude combined with a draft or upToNext; a drafted rib whose sketch is not one straight line; a draft feature whose direction is skewed against the neutral plane or whose neutral plane cuts through the profile; or a face that is not a plane, a cylinder or a cylindrical cone (params.detail names the face and its surface kind).
twistUnsupported
A twisted extrusion whose direction is not the sketch normal.
Two warnings of the end conditions are in Warnings: endConditionFallback (an unreachable end reference ran as a blind extrude of depth, unless the feature sets strictEnd: true, which makes the four unreachable codes above errors) and endRefRelinked.
The result of a boolean could not be assembled into a valid solid. params.hint suggests moving the tool by about 0.01, uniting touching bodies first, or giving the feature a fuzzy tolerance / autoFuzzy: true. When the cause is known: hostFace, toolFace, gap (two nearly coincident free-form walls); or faces, issue (openEdge, nonManifoldEdge, badPairing) and at (the faces and a point at the first bad edge).
booleanTangent
The result has an odd Euler characteristic: the operands touch tangentially. params: euler, hint.
booleanBudgetExceeded
The boolean stopped retrying because it had already run long. params: budgetMs, elapsedMs, hint.
booleanVolumeMismatch
The boolean produced a valid body whose volume or box is impossible for the operands (material dropped or added); the body is left as before. params: what (volume or box), expected_min, expected_max, got and hint.
cutNoEffect
A cut that removes nothing (a tool that misses the body). The body is unchanged. It is reported in errors.
combineEmpty
combineintersect of lumps that do not overlap.
bodyNameConflict
A body name that a live body already has. params: name, features (the feature that made that body and the one that asked for the name).
ambiguousBody
combine.target names several bodies. params: name, candidates ({ lump, face }).
A face move or offset produced no valid body. params.detail; for a curvature or thin-gap limit also limit, minRadius, maxThickness, face.
moveFaceUnsupported
A face move of a surface or option the kernel does not offset.
pressPullUnsupported
A pressPull of a face that is not flat, or of a face of a surface body. params.detail. A run that cannot be built is moveFaceFailed (with maxSize for the distance), a draft that closes the face is draftTooLarge.
alignPipeCutOneBody
pipeCut edges that belong to different bodies.
pipeCutFailed
The pipe cannot be built: an edge without length, or an edge type that is not supported. params.detail.
pipeCutNothingLeft
The pipe removes every face.
pipeCutRadius
The pipe radius is larger than the bend radius of an edge, so the tube folds over itself. params.max is the largest radius that does not.
A fillet or chamfer pick {faces, at} does not resolve to an edge.
blendFailed
The blend could not be built. params.detail.
blendOverflow
The blend leaves its faces: the radius is too large for the faces it rolls on. params.detail; max is the largest radius that fits, when it can be computed.
blendG2TooLargeMax
The same for a curvature-continuous fillet. params: max, shape.
blendSize
No blend fits between the two faces.
variableRadiusMismatch
A variable-radius fillet gives two different radii at one shared vertex. detail names both radii and the vertex.
blendCorner
The corner patch of a vertex with several blended edges cannot be built (the edges are not perpendicular). params.hint: fillet concave and convex edges in separate features.
blendNonManifold
A free-form blend met an edge that does not have exactly two faces.
blendTolerantEdge
An edge of imported geometry carries a tolerance, so there is no exact intersection to roll along. params.detail names the edge and the tolerance.
blendTooLarge
A vertex chamfer distance reaches the far end of an edge, or the contact line of an interpolated blend falls outside its face.
blendUnsupported
A blend on an edge type or configuration that is not built (a vertex chamfer on curved edges).
chamferVertexEdges
A vertex chamfer needs a vertex of exactly three edges.
filletRho
A conic fillet rho outside 0 to 1.
filletShape
A curvature-continuous fillet shape outside the allowed range.
fullRoundUnsupported
A full-round fillet with the same face twice, or a centre face that is not adjacent to both sides.
The wall is too thick: an offset passes the centre of curvature of a face (limit: "curvature"), or two faces are closer than twice the wall (limit: "thin"). params: detail, limit, minRadius, maxThickness (a safe thickness), face.
shellFailed
The shell could not be built; curvature was not the limit, or the boolean failed.
shellUnsupported
An opened face of a shell is not planar.
offsetUnsupported
A shell of a surface or edge type that the offset cannot rebuild. params.detail, and a hint when the cause is a fillet on a drafted edge (shell before the fillet, or remove the draft). A face move reports the same cause as moveFaceUnsupported.
offsetTooLarge
A shell offset reaches the centre of curvature of a face. Carries the same limit params as shellTooThick. (sketchOffset uses the same name for an arc or circle that would vanish, in its result.)
offsetDegenerate
An offset met an edge that reverses (detail: “an edge reverses”). The offset code is offsetDegenerate; a shell reports it as shellTooThick, and a face move reports a failed offset as moveFaceFailed with this text in detail.
draftParallelFace
A draft of a face parallel to the neutral plane.
draftTangentFaces
Two faces of the draft are tangent to each other.
draftAxisNotParallel
A cylinder or cone face whose axis is not parallel to the pull direction.
draftFailed
The draft could not be built; no interior point on a face.
A loft section sketch does not give exactly one profile: it has several closed profiles, or (for a surface loft) is not one open chain.
loftProfileOpen
A solid-loft section is not closed.
loftProfileNotPlanar
A section is not planar.
loftProfileSelfIntersect
A section’s outline crosses itself. detail, hint.
loftSectionTooSmall
The same, with a section small against the loft length.
loftInvalidResult
The solid built from the sections failed validation under every matching strategy. detail, hint.
loftFailed
The loft could not be built (for example guide curves with a point section, an unsupported guide influence). detail, hint.
loftTangentEdges
Any truthy startTangent, endTangent, startContinuity or endContinuity on a loft. The check runs before the loft is built and always fails: tangency to adjacent faces is not available. Remove the fields.
loftGuideInvalid
A guide cannot be used: it is not a curve or has no length, two guides touch a profile at the same point, or the guides cannot be matched to the sections. detail says which.
loftGuideMiss
A guide misses one of the profiles (detail: “the guide misses profile N”).
loftGuideOrder
A guide meets the profiles out of order, or the guides meet the profiles in different orders.
loftCentreLineInvalid
The centre line is not a single open chain of supported curves in a sketch.
loftCentreLineKink
The centre line has a corner; its pieces must run on tangentially.
loftCentreLineTight
The centre line bends too tightly for the sections.
loftCentreLineReach
The centre line does not reach a profile.
loftCentreLineApex
A curved centre line with a point (apex) end.
loftCentreLineGuides
A curved centre line together with guide curves.
sweepPathInvalid
The path sketch is not one connected open chain of supported curves.
sweepProfileNotNormal
The profile plane is not nearly perpendicular (within 15 degrees) to the path at its start.
| sweepFailed | A guided sweep whose profile is not valid. |
| sweepGuidesCount | More than two guides. |
| sweepGuideStretchTwo | Stretch mode needs exactly two guides. |
| sweepGuideNotTouching | A guide does not touch the profile. |
| sweepGuideNotAlong | A guide does not advance along the path direction at all, so the section planes never meet it. |
| sweepGuideShort | A guide advances along the path but ends before a section plane reaches it. |
| sweepGuidesSamePoint | Two guides meet the profile at the same point, or coincide at a section. |
| sweepGuideDegenerate | A guide is not a curve or has no length. |
| sweepGuideOnPath | A guide lies on the path itself at a section, so it gives nothing to scale or turn by. |
| sweepGuideMissing | A guide reference does not resolve to a curve. |
| sweepGuidesTwist | Guides together with a twist. |
| helixNeedsCircle | The helix sketch has no circle to take the radius from. |
knit with solid requested, but the sheets do not close; params lists the open points.
knitNearMiss
knit: two edges that should be joined diverge by more than 100 tolerances at their midpoints (detail: “edges diverge: …”).
fillInvalid
The edges of a fill do not form one chain, or the patch is not a valid face.
fillNotClosed
The chain of a fill is open.
fillFailed
The patch of a fill is not a valid face (a parameter area of zero). detail.
extendNotBoundary
extend of an edge that is not an open boundary edge.
extendNoTarget
The extension never reaches its target.
extendPointBehind
The extension target lies behind the edge.
extendFolds
The extension would fold.
extendUnsupported
The sheet or edge is not one the extension handles: a boundary shared with other faces (only single-face sheets are extended), or an edge that is not a straight line of a planar sheet.
freeformOneFace
A freeform edit with control point edits on more than one face.
freeformEntryInvalid
An edit entry is invalid. params.entry (1-based).
freeformEntryPlane
An edit entry has no usable plane. params.entry.
freeformCrosses
The edited surface would cross other faces.
freeformNotSymmetric
A symmetric edit whose control net is not symmetric.
rebuildPeriodicFace
freeform rebuild of a periodic face.
rebuildTooFine
The rebuild asks for more than 50 spans.
rebuildFailed
The rebuild could not fit a surface.
thickenFailed
The thickened body is not closed.
thickenReach
The thickening offset cannot reach across an edge.
thickenTooThick
An edge vanishes at this thickness.
trimNoIntersection
The tool does not cut the surface.
trimPieceLoop
The kept piece of a face could not be closed into a loop. The trim is not applied.
warnings has the same shape as errors and means the feature ran. A client shows them as notes.
Code
Cause
booleanFuzzy
The result depends on a fuzzy tolerance. params.tolerance is the value that decided it.
endConditionFallback
An unreachable end reference ran as a blind extrude. params: end, reason, fallback, depth, and the params of the reason.
extrudeZeroDepth
A blind or mid extrude has a depth of zero or less, or none (also when an expression evaluates to 0). It was built as a sliver of 1e-6 mm, as the reference does, which is not a usable solid and can make a later union fail with booleanFailed / openEdge. params: depth, built, hint.
sheetCutFallback
A plain extrude cut of a folded sheet was tried as a sheet cut, which refused, so it ran as an ordinary cut of the solid; the part is no longer an unfoldable sheet (no flat pattern, no bend table). params: detail, hint, reason (the code of the sheet-cut refusal), reasonDetail (its detail, when it has one).
endRefRelinked
The end face id no longer exists; the face was found again. params: from, to.
holeDowngraded
A counterbore or countersink was drilled as a simple hole because its step or cone dimension is missing. params: requested, built, missing, detail, hint.
threadDiameterMismatch
The hole or shaft diameter does not suit the thread. params: expected, actual, size, standard, internal, nearest, hint.
threadModelFallback
A modelled thread could not be built and stays cosmetic. params: reason, hint.
threadNotCarried
A pattern or mirror copy could not carry a thread over. params: thread, face, reason, hint.
cornerNotTangent
Blended edges meet at a corner that is not tangent. params.deviation in degrees.
filletRadiusApproximated
A fillet used an approximated radius.
unknownField
A feature carries a field its type does not read, usually a misspelling. params: fields (the names, in document order), suggest (only for names close to a known field: {"depht": "depth"}), detail, hint. See misspelled fields.
Sketch features with text can fail with textEmpty (empty string), textNothingToDraw (only blanks or unknown letters), textFontNotLoaded, textFontMismatch (fontHash does not match the loaded file), textBadHeight (not a number in 0 to 1e5), textBadArc (radius not positive), textBadPath (the path of a text on a path is not a curve of the sketch or has no length) and textBadValue (a position, angle or spacing is not finite, or spacing is outside 0 to 20). Loading a font can warn with fontKerningIgnored, fontLigaturesIgnored, fontVariableDefaultOnly, fontCollectionFirstFace, fontCffApproximated, fontNoCapHeight, fontOverlappingContours, fontEmbeddingRestricted, fontNoSubsetting and fontNoLatin. Text and fonts gives the causes.