Troubleshooting

The Troubleshooting Mindset

When something goes wrong in TouchDesigner the problem is almost always visible in the network if you know where to look. Unlike traditional programming where a crash produces a stack trace, TouchDesigner shows errors in situ — on the affected operator, in the Textport, or in an Info DAT. Your first habit should be: scan the network for red operators, then read the error text carefully.

Red Operators: Cook Errors

When an operator fails to cook, its tile turns red (or shows a red border, depending on the TD version). This means the operator could not produce valid output this frame.

How to read the error:

1. Press I while the red operator is selected. This attaches an Info DAT to it.
2. Look at the Info DAT’s output — the Error row will contain a human-readable description.
3. Alternatively, hover over the red operator. A tooltip may show the error message.
4. Open the Textport (Alt+T). Python errors and cook errors are logged there.

Common cook error causes:

• Missing input. An operator expects an input but nothing is wired to it. The Render TOP with no Camera COMP input, for example. Fix: wire the expected inputs.
• Incompatible input type. Wiring a SOP output to a TOP input creates a “cannot connect” situation. This usually silently does nothing — no wire appears — but if you have an intermediate bridge operator with a broken input, the bridge will error.
• File not found. A Movie File In TOP or Audio File In CHOP with a bad file path turns red. Check that the file exists and the path is correct (relative to the .toe file’s location, or an absolute path that is valid on this machine).
• Shader compile error. A GLSL TOP or GLSL MAT with a syntax error in its shader code turns red. The Textport shows the GLSL compile error with a line number.

“Unable to Cook” Errors

This specific message means the operator tried to cook but one of its required inputs was itself in an error state. It is a cascading error — fix the upstream red operator and this one will likely recover automatically.

Trace the red colour back to its source: the operator with the original error (not the cascade) is the one that has its own error message in the Info DAT.

Bypassing to Isolate Problems

When an error is in a long chain and it is not obvious which operator is causing it, use bypass (press B on selected operators) to temporarily remove nodes from the chain. If bypassing an operator makes the downstream chain go from red to green, that operator is the culprit.

You can also use the Cook flag (the lightning bolt icon on operator tiles) to disable cooking on specific operators. A disabled operator does not cook at all and passes its last good output or a default value — useful for freezing a section of the network while you debug another.

Frame Rate Drops: Understanding the Performance Monitor

When your project drops below its target FPS — the number in the Timeline falls from 60 to 45, or stutters — open the Performance Monitor (Ctrl+Shift+P, or Dialogs > Performance Monitor).

The Performance Monitor lists every operator that cooked this frame, sorted by the time it took. The unit is milliseconds. At 60 FPS, your total budget is about 16.7 ms per frame. At 30 FPS it is 33.3 ms. If any single operator is consuming 10 ms or more, that is your primary bottleneck.

Common causes of frame drops:

• High-resolution TOPs. A Blur TOP at 4096×4096 does far more work than at 1280×720. Reduce the resolution in the Common tab of the relevant TOP, or in the TOP that created the texture in the first place. Use the smallest resolution that gives acceptable quality.
• Too many cooking TOPs. Every TOP that cooks costs GPU time. Use the cook flag to disable TOPs that are not currently needed (branches of the network that are “off” but still cooking).
• Unnecessary feedback loops. A Feedback TOP that feeds into itself and into several downstream chains forces the entire chain to cook every frame. Design feedback paths carefully.
• CPU-heavy CHOPs or SOPs. A Script SOP running complex Python geometry every frame, or a SOP to CHOP on a dense mesh, can stall the CPU and block the GPU pipeline.
• Video decoding. A Movie File In TOP decoding a high-bitrate, high-resolution video file on the CPU. Use GPU-accelerated codecs (HAP, or HEVC with hardware decode), or pre-process video to a lower resolution.

High GPU Memory Usage

TouchDesigner stores textures in GPU memory (VRAM). Running out of VRAM causes severe slowdowns or crashes. Signs of memory pressure: the system becomes sluggish, operators start erroring with “out of memory” messages, or the OS starts paging.

Reducing VRAM usage:

• Lower texture resolutions. 1920×1080 uses 4× the VRAM of 960×540 at the same pixel format.
• Change pixel format from 32-bit float (32-bit float (RGBA)) to 16-bit float or 8-bit where the precision is not needed. Change this in an operator’s Common tab > Pixel Format.
• Disable the cook and viewer flags on branches that are not currently active.
• Use the Movie File In TOP’s Preload Memory setting carefully — preloading long videos into GPU memory is expensive.
• Check Dialogs > GPU Memory Monitor to see which operators are using the most VRAM.

The Non-Commercial Licence Watermark

If your output has a diagonal watermark text reading “TouchDesigner Non-Commercial”, you are in Non-Commercial mode and your output resolution exceeds 1280×1280 pixels.

Solutions:

• Reduce your output resolution to stay within 1280×1280.
• Upgrade to an Educational or Pro licence.
• For many installations and performances, 1280×1280 is entirely workable.

The watermark appears at the final output stage — if you are rendering to a Window COMP at 1920×1080, you will see it. But the internal network can process at any resolution. If you are doing resolution-intensive work internally and only outputting a thumbnail for monitoring, the watermark may not appear in the thumbnail.

Python Errors

Python errors appear in the Textport (Alt+T). The Textport is the first place to look after any change to a Python script or expression.

“AttributeError: ‘NoneType’ object has no attribute…“ — The op() call returned None, meaning it did not find an operator with that name. Check the name in the op() call: it must exactly match the operator’s current name, including capitalisation. Remember that renaming an operator breaks all existing op('oldname') references.

“SyntaxError: invalid syntax” — A Python syntax error in a script or expression. The Textport shows the line number. Common causes: a missing colon at the end of a def or if line, mismatched parentheses, or a Python 2-style print statement (print x instead of print(x) — TD uses Python 3).

“NameError: name ‘x’ is not defined” — You referenced a variable that does not exist in the current scope. In parameter expressions the available globals are limited (me, op, absTime, math, tdu, project, ui). If you need a custom function, define it in a Text DAT, import it into a Script DAT, or use the mod object.

“ZeroDivisionError” — A division by zero in an expression. This is common with expressions like op('audio1')['rms'] / op('audio1')['peak'] when the audio is silent. Guard against it: val / max(op('audio1')['peak'], 0.0001).

“No Such Operator” Errors

The op() function returns None when it cannot find an operator at the given path. If you then try to access a parameter on the None result, you get an AttributeError.

Debugging op() paths:

• In the Textport, type: print(op('your_operator_name')). If it prints None, the name is wrong.
• Try the full absolute path: op('/project1/base1/your_operator_name').
• Check that the operator is in the same COMP level as the script. An op('noise1') in a Script DAT inside base1 looks for noise1 inside base1, not in the parent.
• Use op('../noise1') to go up one level, or op('/project1/noise1') for an absolute path.

Resetting an Operator to Default

If an operator’s parameters have become a tangled mess and you want to start fresh:

• Right-click the operator tile and choose Reset to Defaults. All parameters return to their factory values. Warning: this cannot be undone with Ctrl+Z.
• Alternatively, delete the operator and add a fresh one.
• To reset a single parameter without affecting others, right-click the parameter label and choose Set to Default (or press D while hovering over it).

Operators Cooking Every Frame Unexpectedly

If an operator is cooking every frame even when you expect it to be static, something upstream is flagging it as dirty on every frame. Common culprits:

• An expression containing absTime.seconds or absTime.frame changes every frame by definition.
• An LFO CHOP or Noise CHOP whose output feeds into a CHOP export on a parameter.
• A Movie File In TOP reading from a live video source (webcam, NDI).
• A Web Client DAT making HTTP requests on a short polling interval.

Open the Performance Monitor and look at the cook time of the suspicious operator. Then work backward through its inputs looking for the source of the continuous dirty flag.

Quick Reference: Error Checklist

Symptom	First place to look
Red operator	Press I for Info DAT, read the Error row
Cascade of red operators	Find the first red upstream operator
FPS dropping	Ctrl+Shift+P → Performance Monitor
Python errors	Alt+T → Textport
op() returning None	Textport: print(op('name')) to verify path
Watermark on output	Output > 1280×1280 in Non-Commercial mode
Missing asset / file not found	Check file path in parameter; use relative paths
VRAM / memory errors	Reduce texture resolutions and pixel format
Operator cooking when it shouldn’t	Performance Monitor → trace upstream

Troubleshooting becomes faster as you build intuition for the patterns. The most important habit is to read the error message exactly as written rather than guessing — TouchDesigner’s error messages are usually quite specific about what went wrong and where.

---

This concludes the starter series. You now have the vocabulary and mental model to navigate the TouchDesigner interface, understand the six operator families, build networks from scratch, animate parameters over time, and diagnose problems when they arise. The beginner series picks up from here with audio reactivity, 3D scenes, and building reusable components.