Troubleshooting in TouchDesigner
TouchDesigner is an incredibly flexible tool, and with that flexibility comes the potential for intricate and difficult to find problems in your creations. This page is a brief introduction to the most important troubleshooting techniques and tools you'll use when building TouchDesigner networks. Of course, every problem is unique to its context so it will be up to you to determine which of these best suits your needs. To that end, this page will familiarize you with the range of tools at your disposal.
Troubleshooting, or debugging, is different from optimizing, which focuses on making your networks run efficiently and quickly. For optimization information see Optimization.
Many (but not all) of the techniques described below will require a basic understanding of Python.
Important: If you find a bug in TouchDesigner itself, please report it to Derivative.
The first place to look for information about TouchDesigner features is in this wiki, which serves as the official TouchDesigner documentation. Often, the documentation will provide clues (if not answers) about any problem you are having with a feature. If necessary you can download the entire wiki for use offline.
In addition to using the wiki's search feature, there are portals in the TouchDesigner user interface directly into this wiki. All Operators have links to their wiki pages in their Parameter Dialog header:
The leftmost button in the bottom header section links to Operator help, and the next button to the right links to Python help.
Also, some Components found in the Palette will have a Help Page custom parameter that opens a browser to that Component's wiki page.
Another common place to get help or information about TouchDesigner is in the TouchDesigner Forums. There is a strong and helpful community of users and Derivative staff to draw on. As on any forum, search for answers first before posting your questions, and when you do post be as clear and concise as possible.
Finding errors in networks is generally easy because nodes with errors will be displayed with an error marker, a red circle with a black X. To get info about the error, click on the error marker or middle-click anywhere on the node. Generally, when the error is fixed, the error flag will disappear immediately.
If there is an error anywhere inside a Component, it will show an error marker, so often fixing an error will require entering components until the actual source of the error is found.
Errors Dialog and Error DAT
The Errors Dialog, found in the Dialog menu, will allow you to see and jump to all current errors. It also allows you to filter errors by Operator type, specific operator, and error message. The Error DAT is very similar to the Errors Dialog, but in a DAT format, and with callback functionality.
OP.errors() and OP.scriptErrors()
Another way to find all node errors in your network is to open a Textport and enter the command
op('/').errors(recurse=True) to get all node errors or
op('/').scriptErrors(recurse=True) to get all scriptErrors. This will print a list of all errors and which node they are associated with, or you can specify a network path and print all errors under that network. Occasionally you may find that a Component has a child with an error, but the error disappears when you enter its parent. The Error dialog, the Error DAT or the
errors() method is a good way to find out what the error is without having to actually navigate to its network.
Getting Info with Info CHOP, Panel CHOP and Info DAT
You will sometimes want to watch values on a node while researching its error. There are a few Operators that are useful for this. The Info CHOP holds numeric information about the node referenced in its Operator parameter. Similarly, the Panel CHOP holds numeric information about a Panel Component's panel values. TIP: You will notice that the Info CHOP holds panel information as well, but it is best to use a Panel CHOP to watch panel information, as it is sometimes updated more reliably.
Pinpointing Errors with Bypass and Cook Flags
Often when trying to pinpoint an error in a network, you will want to narrow the possible sources down. Using the Bypass Flag to narrow down active Operators will often help you. If you want to turn off an entire network to narrow things down, you can turn off the Cooking Flag of the parent Component.
Using Chop Execute DAT and Parameter Execute DAT to Catch Errors
If you want to print a debug message to the Textport when a certain event happens, you will usually use a CHOP Execute DAT or a Parameter Execute DAT to watch values. For example, the CHOP Execute DAT can be used in tandem with the Info CHOP and Panel CHOP to notify you of changes to those values. Note: the execute DATs can be used to react when a change happens, but they have no direct way to trace what caused that change. Still, knowing when something happens can be very helpful in finding what causes it.
Troubleshooting in Perform Mode
When troubleshooting in Perform Mode, the editor is hidden but you will still want access to a lot of info you would normally get from it. The main technique to use here is floating viewers, which stay open when you enter Perform mode. So, if you open floating viewers (use the RMB context menu View... option) and Parameter viewers (RMB context menu Parameters...) while in Editor mode, then enter perform mode, you will have access to the things you want to keep an eye on or change. Floating Textports will also stay open in Perform mode. Another important technique in Perform mode is using F10 to open the network of whatever panel your mouse is over. You can also use F9 to open the parent of that panel, with the network view focused on the panel Component. These hot-keys allow easy access to the specific parts of your Perform mode control panel that need attention.
Troubleshooting Disappearing Errors
Sometimes when you load up a .toe file, you see a network with an error, but when you enter the network, the error is gone. This is because an error can occur if a node hasn't been asked to load or cook, etc. However, manually looking at that node, or something that depends on it, will then trigger that node to update.
Unfortunately these errors generally need to be looked at on a case by case basis, but quite often they don't affect the performance after startup.
For a list of errors, open the Error Dialog instead of diving into the network, since that triggers updates.
If the error is a cook order issue that isn't easily resolved, you can sometimes use a startup script to force cook this node in a specific order.
Under-cooking is when an Operator should be updating but for some reason is not. If you change data in one Operator, and it is not causing itself or another Operator looking at that data to update (cook) it may be an under-cooking problem. An important technique for verifying such an issue is to use an Info CHOP to monitor cook counts. All under-cooking issues should be reported to Derivative.
If you have an issue where your operators work properly in the Editor, but not in Perform mode, try turning off all your viewers in the Network Editor using the Viewer Flag. Because TouchDesigner only cooks nodes that are being used, it may be that you have no issues in the Network Editor because the node's viewer is using the node.
Because TouchDesigner is a realtime engine and does not use a breakpoint/step debugger for Python, debugging can be a bit tricky. When working with Python, the Textport is your best friend, and you will want to have one open at all times. Python errors are printed to the Textport (as well as showing up in error markers on nodes) and you will often want to print your own debug messages. TIP: if you find a floating textport inconvenient, use the Pane Bar to split your network view and change one of the pane types to Textport and DATs.
Python Error Markers in Networks
As with other Operators, DATs with Python scripts will show error markers when they have a problem. If a DAT is being used as a Python script and it has an error while compiling, it will display an error marker. Again, like other Operators, you can see what the compile error is by clicking the error marker or middle-clicking the node. When the compile error is resolved, the marker will disappear.
When a Python script has a runtime error within a script, things work a little differently. The error marker will be placed on the DAT containing the script where the error started. This means that although the error may have happened in one module, the marker will be on the module that called that one! Luckily, the entire error stack (the chain of Python commands leading to the error) can be found in the error marker info, and usually will be printed to the Textport as well.
Getting Debug and Error Information
As mentioned above, because of TouchDesigner's realtime nature, the method for getting debug information from Python is to output it from scripts as they run. Here are a few important commands and techniques:
debugcommand prints any number of objects to the textport. It works very much like the Python
debugoutput will also append the script and line number from which
debug("Testcomp:", myComp.path, myComp.par.display)
When outputting information from a Python script for debugging purposes, always use the
debug command. When using
debug always outputs the location it was called from, you will always be able to find and remove your debugging code easily. As an added perk,
debug outputs more detail than
- Sometimes you will want to see what Python calls have led to running one of your Python scripts. To print the stack of Python calls, use
print(project.pythonStack). Python users may recognize that this parallels the
traceback.print_stackmethod. It is safer to use
project.pythonStack, because the Python version occasionally causes unwanted error markers to be placed in TouchDesigner networks. The
project.pythonStackmethod has also been customised to provide additional information for TouchDesigner operators. The corresponding
project.stack()will give the stack of operators being cooked and evaluated.
Outputting to DATs Instead of Textport
The above methods automatically output to the Textport, and that will suit most debugging needs. Occasionally, though, you may want to store larger amounts of debug data, or be able to keep the data around for longer, such as between file saves. To do this, you will want to output to a Text DAT or a Table DAT. Using a Table DAT can be helpful by organizing debug information into columns.
Sometimes you will want to stop code execution at a certain point. To do this, simply raise a Python Exception. Code execution will stop and the error will be reported via Error Marker and Textport. When raising an exception, it is generally good practice to add a useful message.
raise Exception("Width set to zero in " + parent().path)
For more detailed information about Python Exceptions see: Python Errors and Exceptions
Crashes and Troubleshooting .toe Files
Occasionally, TouchDesigner will crash. It has some nice features to make that less destructive and more diagnosable, which will be described in this section. In addition, every time you save your project, an incremented version is saved in your work folder. This ensures that you can jump back to previous working. Tip: if you find your work folder getting cluttered with these backup files, you can set TouchDesigner to copy them to a Backup folder by setting the Increment Filename on Save Preference.
If you do find your network crashing, especially in a repeatable manner, please .
Crash Auto Save
For almost all crashes, TouchDesigner will automatically save a CrashAutoSave.toe before shutting down. The CrashAutoSave file is your project saved at the moment it crashed. When you load it, it will be in a special safe mode where most functionality is bypassed. This allows you a chance to fix any problems you may have created to cause the crash. When you save this file and reload, it will be in normal mode again.
Tip: if you ever find yourself needing to work with a saved .toe file in the CrashAutoSave safe mode, you can simply change the name of your file to CrashAutoSave and reload.
Startup Error Dialog
Sometimes your network will have errors that occur during TouchDesigner's initial set-up. To get a full report of errors when TouchDesigner loads up, choose Edit>Preferences from the editor's menu. On the General page there is a Show Startup Errors menu that allows you to choose whether you want to see the Startup Error Dialog when there are warnings or errors (Warnings setting) or only when there are errors (Errors setting). The next time you load TouchDesigner, you will see the Startup Error dialog if the criteria is met.
A good way to diagnose crashes like Touchdesigner simply disappearing on startup or later is to install the ‘Windbg Preview’ app from the microsoft store. You can launch your app from within there and keep pressing the play button until it catches the actual crash (it may pause once or twice on startup due to an exception). From here that may give you a hint as to what is going on. A
.dmp file can also be created which you can send to us to inspect further:
ToeExpand and ToeCollapse Utilities
In rare cases, you may want to disassemble a .toe file into something ASCII readable. To do this, use the Toeexpand and Toecollapse programs provided with TouchDesigner in its installation directory. Reasons to use these include fixing something in a file that won't load or searching for a hard-to-find bit of text. This also allows you to use a diff program to compare two .toe files find all differences.
Reporting a Bug to Derivative
User reports are an important source of information about bugs in TouchDesigner, and your feedback is appreciated. That said, before reporting a problem as a software bug, always try to use the above techniques to make sure that the problem is in the software.
To report a bug, please email (firstname.lastname@example.org) or post your .toe file on the forums, along with how to replicate the error, and any .dmp files or crash reports created (in the case of a crash). On Windows, the .dmp file will be saved in your project directory. On macOS, you can find the crash reports via Applications->Utilities->Console. The Crash reports will be under User Reports and named TouchDesigner_date-xxx.crash. Posting problems to the forum is best, but if your project contains private data or techniques, feel free to email.
When reporting a bug, please attempt to do the following:
- Create a case that is as easy to reproduce as possible. Make it fast and simple for Derivative to see your bug.
- Trim down your file as much as possible. Remove everything you can to create a small file size and easily understandable network.
- Make sure that your file does not require extra media. Many Operators can be "locked" to preserve their data and remove their dependence on external files. If external files are absolutely necessary, create a ready-to-run zipped folder with your .toe file and all required media.
- When sending zipped files, use .zip, not .rar, .7z etc. For larger files, feel free to use google drive, dropbox or something similar.