Consequence for any script: read back every enum-like value you write, against the port's own list of legal values rather than against your expectations. The mechanism is one call and needs no prior knowledge of any node's vocabulary — it is the first item under Configuring ports.

Until the unit is reported: treat any parameter called Angle, Rotation, Tilt, Twist or Bank as radians, and Strength on a deformer as radians too — it is an angle despite the name. Convert on the way in rather than after the fact.

Silent · Invented facts

A fetched page is a summary of that page, not the page

An assistant's fetch tool usually hands back a summary written by a smaller model, not the document. Where the page's own text is thin — names set as images, content assembled by script — the summary fills the gap with something plausible, and nothing marks the difference.

Measured on this very documentation set: the product portal carries only the one-line descriptions in its readable text, not the product names. A summary of it returned a product name that appears nowhere on the page, and three further names came back subtly altered — Maxon App Manager for Maxon App, After Effects Integration for Maxon Studio, ZBrush Paint for ZBrush for iPad. All four read perfectly plausibly. The error would have travelled silently into a briefing and misdirected every later question about those products.

The habit: name a product from its own documentation, not from a page that lists it. A page title is evidence; a description next to a link is not. This is the same rule as never invent a validity indicator, applied to reading rather than measuring.

Misread signal · Wasted turns

A render in progress is not a render that failed

render_preview_image works on its own thread so the application stays usable. The first call starts the render and returns status: rendering; a later call collects the image, or reports pass_progress while it works. That is the protocol doing its job. Read the repetition as an error — and it looks like one, the same call issued three times in a row — and you will either start over or switch to a renderer you did not need, with no failure anywhere in the record.

Measured on a scene of thirty cube objects at 1024 × 768:

The render is not what costs; the polling is. Each collection attempt is a full round trip. Choose the cheapest renderer that can answer the question you actually have — hardware approximates or ignores scene lighting, sky and most shader behaviour, so it settles a question of geometry in a fraction of the time and cannot settle one about light at all.

Leftovers

What you add in order to look is still there afterwards

Inspecting a scene invites building a little scaffolding: a camera placed for a good view, a target tag to aim it, a converted copy of a generator to measure, a change of the active camera or the active view. All of it lands in the person’s document and stays there. A review camera left behind in a scene someone then saves is a puzzle for them and a support question for you.

The habit: put the scene back the way you found it, in the same turn, or name what you left and why. And prefer the inspection that leaves nothing at all — reading a matrix changes nothing, converting a generator changes the document.

Not readable

A node instance does not report its own asset id — probe for it

node.GetValue("net.maxon.node.base.assetid") returns None. FindNodesByAssetId returns an empty list for an id that does not exist and the matching nodes for one that does, which turns identification into a cheap loop over candidates:

for a in ["net.maxon.node.if", "net.maxon.node.condition", "net.maxon.node.switch"]:
 print(a, len(H.FindNodesByAssetId(sg, a, True)))

Confirmed ids for frequently used nodes:

Careful: Port names do not identify a node type. If and Clamp both expose in1 / in2 / in3, but for If that is condition / true / false and for Clamp it is value / low / high. Confirm the asset id before assuming what a port means.

Easy to miss

Ports have children, and some connection targets sit deep inside a node

GetInputs().GetChildren() returns only the top level. Bundles, variadic slots and the ports of a node's inner structure are nested further down, and a legitimate connection target can live several levels in — a path such as node/</some.bundle/_0/geometry is normal. If you need to find one, walk recursively over GetChildren() looking for the port id:

hits = []
 def walk(n, path, depth=0):
 if depth > 6: returntry: kids = list(n.GetChildren())
 except Exception: returnfor c in kids:
 p = path + "/" + str(c.GetId())
 if str(c.GetId()) == wanted: hits.append(p)
 walk(c, p, depth + 1)

Careful: Record a connection's full endpoint path before you break it. A target you found by following an existing wire may be very hard to locate again from the node's port list alone.

Silent · Wrong results

Every node family has its own mode abbreviations

There is no shared convention across nodes, and the display labels are not the ids. Values confirmed by reading the ports:

Compare is the one that catches people. Because add, sub and sin read like plausible spelled-out words, the natural guess for a comparison is lessthan — which is stored, silently, and leaves the node comparing something other than what you wrote. Everything gated by that comparison then behaves unpredictably, which sends you looking at the branches instead of at the operation.

Silent

When you do set a datatype, use the canonical spelling

For a three-component vector that is net.maxon.parametrictype.vec<3,float>. The variant net.maxon.parametrictype.vec<3,float64> resolves to the same registered 24-byte type and computes correctly, but it is not on the port's enum list, so it produces the spurious extra dropdown entry described at the top. The friendly-looking string "Vector" is accepted and completely inert.

Note that float means Float64 in maxon; vec<3,float32> is a different, 12-byte type. You can confirm any spelling resolves with maxon.DataType.Get("..."), which takes a str, not a maxon.Id.

Silent · Order matters

Setting datatype and operation together wipes the datatype

The two cannot be applied in one description. Set datatype first and commit, then set operation in a second transaction. The same caution applies to any pair where one port reconfigures the other's meaning.

Silent · Wires lost

Some mode ports replace the port set — and the connections with it

A datatype or operation change usually leaves a node's ports where they were. A few mode ports do not: they reconfigure what the node is, and the inputs are swapped for a different set. A stream-mode toggle on an aggregating node, for instance, replaces a single in with stream plus two domain ports. Anything wired to the port that disappeared is silently gone — no error, and the node looks fine because it still has inputs.

So: set that kind of switch before wiring the node, never after. If you have to change one on a node that is already connected, re-read the port list afterwards and rebuild every wire into it. Two habits make this cheap — keep the wiring in an explicit table you can re-run, and dump the node's port ids before and after the change rather than assuming they matched.

Silent · Dead guards

A constant Value port rounds to three decimals

Measured: 1e-5 → 0, 1e-4 → 0, 1e-3 → 0.001. Any epsilon smaller than 0.001 entered on a Value node is stored as zero, which quietly turns a division-by-zero guard into no guard at all. If you need a smaller threshold, compute it inside the graph rather than typing it into a constant.

Silent · Costs an hour, twice

A value written to a connected port is discarded without a word

SetPortValue on a port that already carries a wire does nothing. No error, no warning, no return value to check — the wire keeps winning and the number you wrote is gone.

Obvious stated plainly, invisible in practice, because the two situations that produce it both look like ordinary work:

— Rewiring an If. Swapping which branch is the constant and which is the connection. Setting in2 to a constant while the old wire into in2 is still attached leaves both branches computing the same thing. The node still evaluates, the result is plausible, and the symptom appears far downstream — two points of a pattern landing on top of each other.

— A/B testing a Switch. Writing 0 and then 1 into a Switch’s index to compare two paths yields two identical measurements when that index is driven by a wire. That reads as “the change had no effect”, which is exactly the wrong conclusion to draw.

So: detach first, then set. And when a measurement says a change made no difference, confirm that the knob you turned was connected to anything at all before believing it.

p = port(node, "in", "in2")
 for c in list(p.GetConnections(maxon.PORT_DIR.INPUT)):
     maxon.GraphModelHelper.RemoveConnection(c[0], p)   # first
 p.SetPortValue(0.0)                                     # then

Silent · Editor-only error

An array port needs an array datatype spelling

net.maxon.parametrictype.array<float> — writing the element type float on an array container port is accepted by the API and produces the badge "Type 'Float64' is not an array or array container type" in the Node Editor, which script cannot see. The element getters reading that array need types consistent with its element type too, or their output stays invalid while every read-back you can perform looks correct.

This is the case where the person at the editor is your only error channel. If an array chain evaluates to nothing and the values all read back as written, ask for a screenshot before rewiring anything.

Circuit design · Visible artefact

An easing curve on an interpolation fraction flattens the result at every sample

When you interpolate between two sampled values, it is tempting to run the fractional part through a smooth-step for a "softer" result. Smooth-step has zero slope at both ends, so the interpolated curve arrives flat at every sample: the profile becomes a staircase with rounded steps, it reads as banding, and raising the sample count makes it worse rather than better, because each step gets its own plateau.

Use the fraction linearly and raise the sample count instead. An easing curve belongs where a genuinely flat approach is wanted — a blend that should start and end at rest — not on an index fraction.

Silent · Whole feature lost

Geometry can arrive carrying its tangents and still be evaluated as a polyline

A classic Bezier spline linked into a capsule through an Object Link delivers its control points — and, it turns out, its tangents. But the curve arrives typed as linear, and every evaluation node believes the type. spline.evaluate, spline.length and Resample all walk the control polygon, and the curvature is silently discarded.

It is hard to spot because nothing looks missing: the result follows the spline’s general course, just cutting every corner. Resampling to a hundred points is a good probe — if the resampled polyline comes back with exactly the control-polygon length, the curve is being read as linear.

The fix is one node, net.maxon.neutron.geometry.spline.type, set to bezier, placed where the geometry enters:

curve type   length    distance to the true Bezier curve
 linear       27.371    1.6050
 bezier       30.116    0.0106      # the real curve is 30.103
 bspline      27.368    1.6047

Applying it unconditionally is safe. On a polyline that genuinely has no tangents — the output of Assemble Spline, say — retyping it as bezier moved points by at most 0.0094 over a 60-unit curve, because a cubic through collinear control points is still a straight line. There is no need to make it an option: type everything bezier on the way in and let the curves that have curvature use it.

Silent · Dead end

A valid curve type can make every later evaluation return nothing

Assemble Spline carries a splinetypein port. Its registry holds exactly three entries, and anything else raises — unusually well behaved for this API:

net.maxon.registry.geometryabstraction.curve.types.linear    # default
 net.maxon.registry.geometryabstraction.curve.types.bspline
 net.maxon.registry.geometryabstraction.curve.types.bezier
 # .cubic / .akima -> ValueError

Setting bspline produces a perfectly good spline — the resulting object reports type 3 and the same control point count. But spline.evaluate and spline.length return nothing for it, so a downstream capsule that samples that curve emits zero points, with no error anywhere. The evaluation nodes appear to handle interpolating curves only.

bezier evaluates, but Assemble Spline is given control points and no tangents, so there a Bezier is a polyline with extra steps. If a smoother curve is needed, smooth the control points before assembly instead — Chaikin corner cutting is exactly the subdivision scheme whose limit is the quadratic B-spline, and it leaves a point list the rest of the pipeline can still evaluate.

Silent · Wrong branch

A resource enum delivers its cycle ids, not 0, 1, 2

A dropdown authored in the Resource Editor hands the graph its raw cycle ids, which commonly start at 1000. A three-way selector therefore arrives as 1000 / 1001 / 1002 and every comparison against 0 / 1 / 2 fails the same way, so the circuit looks like it is ignoring the menu. A Modulo 1000 ahead of the comparisons works with both numbering schemes and survives a later renumbering of the resource.

Silent · Feature unreachable

Resource limits clamp a value before the graph sees it

If a sentinel value drives graph logic — "0 means automatic", say — check the parameter's limits first. A MIN of 0.01 means writing 0 silently stores 0.01, and the comparison in the graph is never true. Either widen the limit or put the threshold above it and document that.

for bcd, did, gid in obj.GetDescription(c4d.DESCFLAGS_DESC_0):
 if bcd[c4d.DESC_NAME] == "My Parameter":
 print(obj[did], bcd[c4d.DESC_MIN], bcd[c4d.DESC_MAX], bcd[c4d.DESC_UNIT])

The same loop is the general way to map a capsule's human-readable parameter names to the ids you need for obj[did], since those ids are long nested tuples that are impractical to write by hand.

Silent · Invisible name

The name you create a node with is not the name the person sees

When you call AddChild("MYNODE", …), MYNODE becomes the node's id and the net.maxon.node.base.name attribute stays empty — so the Node Editor shows the generic asset title ("Arithmetic") and the person cannot find your node by the name in your notes. It works the other way round too: a node the person names carries a meaningful base.name and an id that is pure hash. A lookup has to cover both:

def nm(node):
 try:
 v = node.GetValue("net.maxon.node.base.name")
 if v: return str(v)
 except Exception: passreturn str(node.GetId()).split("@")[0]

Two ways to close the gap. Write base.name yourself on the nodes you create, so your names become visible to the person. And to point at a node in conversation, select it rather than describing it:

H = maxon.GraphModelHelper
 gm = graph.GetViewRoot().GetGraph()   # not the ref GetGraph(obj) gave you
 tr = graph.BeginTransaction()
 H.DeselectAll(gm, maxon.NODE_KIND.NODE)
 H.SelectNode(node)
 tr.Commit()

Silent · Wrong node created

Display titles are not unique — ask by asset id, category and ports

Several distinct nodes carry near-identical titles in the browser: a stream-reducing summation in one category and an aggregating one with an operation port in another; a manual array builder and a loop collector. Ask for "Sum" and you have an even chance of getting the one without the port your design depends on — and the mistake surfaces much later, as a port that is not there, in a part of the graph you are no longer looking at.

Name three things in the request: the asset id, the category to find it under, and the ports it must expose. The last one is the check the person can perform without you.

No API · Plan around it

A script can build a graph but cannot place it

Node positions live in an undocumented attribute called widgetDataBlackBox: a DataDictionary holding another DataDictionary whose first entry is a Pair<vec<2,float32>, float32> — the position, and the node’s display width. Reading it works:

def pos(node):
 wd = node.GetValue("widgetDataBlackBox")
 if wd is None: return None# never placed
 inner = [v for k, v in wd][0]
 pair = [v for k, v in inner][0]
 v = pair.GetFirst()
 return (float(v.x), float(v.y))

Writing it does not. pair.Set() raises TypeError: issubclass() arg 1 must be a class for every argument form, maxon.Pair.Create() reports that it “could not find any Alloc function”, and the pair’s datatype id does not resolve from the registry. Replacing the inner entry with wd.Set(key, inner) appended a second entry instead of overwriting the first and left the node broken; only doc.DoUndo() recovered it. The Graph Framework exposes no layout or position interface at all — placement is a Node Editor concern.

What this means for a plan. Creating, wiring, naming, configuring and verifying are all yours. Arranging is not. Every node a script creates returns None from the reader above and draws at the same default spot, so a freshly built graph is one stack of nodes on a single pixel. Say this at the start of a project and schedule a manual arrangement pass with the person, rather than promising a readable graph.

Freeze · Out of memory

Automatic arrangement is priced by graph complexity, not by node count

The Node Editor’s automatic arrangement is the obvious answer to the previous entry, and on a script-built graph it is the command most likely to take Cinema 4D down. On a small graph it works. On a large one the call appears to freeze the application for several minutes and then ends in an out-of-memory warning; the same family of geometric commands includes MoveToGroup, recorded elsewhere here for the same reason.

Node count is not what predicts the failure. Two capsules from one project, arranged with the same command:

The capsule that fails has fewer layers and fewer long wires than the one that succeeds. What it has instead is two and a half times the wires and a 142-node feedback tangle, produced by its Loop Carried Value groups: in the flattened view a layout algorithm builds, those groups feed edges backwards. A layered layout has to break every cycle before it can assign layers at all, and choosing the smallest set of edges to reverse is NP-hard. That is where the memory goes.

The workaround that does work: arrange in blocks. Select twenty to thirty related nodes from script, ask the person to run the arrangement on that selection and park the result, then move to the next block. Blocks of about thirty nodes went through reliably in a 393-node capsule where the whole-graph call did not. Choose the blocks by a name prefix scheme decided before the graph is built — it costs nothing during construction and turns the arrangement pass into a short, mechanical sequence.

Two references · Freeze

Selecting nodes needs the other graph reference, inside a transaction

Two different objects are both called “the graph”. maxon.GraphDescription.GetGraph(obj) returns a NodesGraphModelRef; calling GetGraph() on that graph’s view root returns a GraphModelRef. Read-only helpers accept either, so the difference stays invisible until GraphModelHelper.DeselectAll, which needs the second one. Handed the first, it froze Cinema 4D rather than raising.

Selection is a modification as well: outside a transaction SelectNode raises RuntimeError: No current transaction for modification of NodesGraphModel.

g = maxon.GraphDescription.GetGraph(obj)   # NodesGraphModelRef
root = g.GetViewRoot()
gm = root.GetGraph()                       # GraphModelRef — what DeselectAll needs
H = maxon.GraphModelHelper
tr = g.BeginTransaction()
H.DeselectAll(gm, maxon.NODE_KIND.NODE)
 for n in nodes: H.SelectNode(n)
tr.Commit()
c4d.EventAdd()

Selecting is how you point at a node in conversation, and it is the lever for the block-wise arrangement above. To name a node in your message, read effectivename: it returns the name the person gave the node, and the asset title when they have not named one — in both cases exactly what the Node Editor displays. Note that a name you passed to AddChild is the node’s id, not its name, so it will not appear there.

Stale data

Set a parameter and read the cache in two separate calls

Changing a value and then reading the deform cache within the same exec_python call can return partly stale geometry — some coordinates updated, others not, which reads exactly like a real bug. Calling ExecutePasses yourself does not reliably fix it. Write the parameter, return, then measure in the next call.

Transient

If a parameter stops having an effect, drive the port from a constant before rebuilding

Observed once and worth knowing: a capsule parameter stopped reaching the graph at runtime. Toggling it changed nothing in the measurements, while replacing the same input with a constant inside the graph produced the full effect — so the circuit was right and the binding was not. Reloading the scene restored it.

The general move is to prove where the break is before assuming what it is. Substituting a constant for the parameter separates "the circuit computes the wrong thing" from "the value never arrives", and those two have nothing in common as repairs. Reload before concluding the graph is broken.

False alarm · Cost a wrong fix

A metric that returns the same number before and after is measuring something else

To test whether a surface normal had flipped, one run compared each point’s distance from the model’s bounding-box centre: the sunk point should sit closer to the centre than the lifted one. It reported 13 of 32 periods inverted. The circuit was changed on the strength of it. It still reported 13 of 32 — at every parameter setting, before and after every edit.

The metric was measuring the shape of the model, not the circuit: on a head, the surface normal under the jaw does not point away from the centre, so those periods fail the test whatever the frame does. A result that stays constant across changes which should have moved it is the tell.

The honest metric compared the dip direction against the mesh’s own area-weighted vertex normal — and it had to compare two points at the same position, one lifted and one sunk, not two points half a period apart. That version separated the cases cleanly (9.5° when aligned, 26.4° when not) and showed the change had made things slightly worse, so it came back out.

Two habits: prove a metric on a case whose answer is already known before trusting it, and treat “no change” as a suspect result rather than as evidence. It is as often a broken measurement as a real null.