Reliable 45° corner trim on a CadQuery hex bolt head using a revolved cutter, avoiding face-selection errors

Learn how to cut hex bolt head corners at a strict 45° in CadQuery without fragile face selections: use a revolved cutter for a robust, parameter-safe workflow.

Cutting the upper corners of a hex bolt head at a strict 45-degree angle in CadQuery looks simple at first glance, but a straightforward approach with lofts and face selections can lead to errors. Below is a focused walkthrough that demonstrates the issue, explains why it happens in this context, and shows a reliable way to get the desired geometry.

Goal

Create a hex bolt head whose six corners are trimmed at 45 degrees around the top, producing a clean, uniform angled cut across the corners.

Reproducing the issue

The following code constructs a hexagonal head, attempts to build a lofted cutter, performs a boolean cut, and then tries to target the top face for another cut. It fails with a face-selection error.

import cadquery as cq
from math import sqrt, tan, radians

CAP_D = 20.0
CAP_H = 10.0
BEVEL_DEG = 45.0
ROD_D = 8.0
ROD_L = 30.0

big_R = CAP_D / 2.0
inscribed_r = big_R * sqrt(3) / 2.0
trim_h = (big_R - inscribed_r) / tan(radians(BEVEL_DEG))

head_solid = (
    cq.Workplane("XY")
    .polygon(6, CAP_D)
    .extrude(CAP_H + trim_h)
)

loft_tool = (
    cq.Workplane("XY")
    .workplane(offset=CAP_H)
    .circle(inscribed_r)
    .workplane(offset=trim_h)
    .circle(big_R * 1.1)
    .loft(combine=True)
)

tmp = head_solid.cut(loft_tool)

tmp = (
    tmp.faces(">Z")
    .workplane(centerOption="CenterOfMass")
    .circle(inscribed_r)
    .cutBlind(-trim_h)
)

show_object(tmp)

In this setup, the operation raises the following error.

ValueError: If multiple objects selected, they all must be planar faces.

What goes wrong here

The error indicates that the selection step targets more than one face and that the selection contains geometry that doesn’t satisfy the requirement of planar faces. In practice, that means the subsequent operation cannot proceed with that mixed or ambiguous selection set.

A robust approach: revolve a cutter profile

Instead of relying on a loft and face selections, construct a profile that encodes the 45-degree slope as a simple triangle and revolve it around the bolt axis to form a clean solid cutter. Subtracting this cutter from the hex head trims all corners at the correct angle in one deterministic step.

The idea is straightforward: draw the triangular section on the XZ plane, offset it to the top of the head, and revolve it 360° around the Z-axis. This creates a solid of revolution that intersects the hex head precisely at the intended height and angle.

Working solution

The snippet below builds the head and subtracts the revolved cutter. Adjust the radii and depth to match your head diameter and 45-degree drop.

import cadquery as cq
from math import sqrt, tan, radians

CAP_D = 20.0
CAP_H = 10.0
BEVEL_DEG = 45.0

R_out = CAP_D / 2.0
r_in = R_out * sqrt(3) / 2.0
drop = (R_out - r_in) / tan(radians(BEVEL_DEG))

head = (
    cq.Workplane("XY")
    .polygon(6, CAP_D)
    .extrude(CAP_H + drop)
)

revolve_tool = (
    cq.Workplane("XZ")
    .workplane(offset=CAP_H)
    .move(r_in, 0)
    .lineTo(R_out * 1.1, 0)
    .lineTo(R_out * 1.1, -drop)
    .lineTo(r_in, 0)
    .wire()
    .revolve()
)

cut_head = head.cut(revolve_tool)

show_object(cut_head)

This creates the cutter as a solid of revolution and performs a single boolean cut that trims the top corners uniformly at the specified angle. The cutter geometry is correctly defined; you can shift or resize the profile if you need to fine-tune where it bites into the head.

Why this matters

Parametric CAD is not only about reaching a shape but doing it with operations that stay predictable when parameters change. Face-based selections can become ambiguous after booleans, which can lead to errors or fragile models. A revolved cutter cleanly encodes the 45-degree requirement and avoids ambiguous face selection altogether, making the modeling step more resilient and straightforward.

Takeaways

When the goal is a constant-angle removal around an axis, a revolved cutter provides a clean and robust route. If a modeling step complains about planar face requirements, verify exactly what the selection returns and consider eliminating the dependency on that selection by switching to a solid cutter. For this bolt head task, the solid-of-revolution approach produces the intended 45-degree trims across all corners in one reliable cut.