Is this page helpful?

Troubleshooting#

This page covers common issues, known limitations, and where to find help when working with Material Graph.

Common Issues#

Node Shows Red or Yellow Fringe but Graph Looks Correct#

Cause: The node’s shader definition was not found for the currently active render context. This typically occurs when a required module, plugin, or Sdr definition source is unavailable or the authored shader identifier is invalid.

Fix: Switch to the correct context using the context tabs at the top of the Material Graph window. If the node should exist in the current context, verify that the required module or definition is loaded in Preferences > Material Graph.

Connection Shows as Red#

Cause: The connected ports have incompatible data types. Material Graph highlights mismatched connections in red to indicate a potential issue.

Fix: Hover over each port to view its data type in the tooltip, then verify that the output and input types are compatible. To override the check, enable Force Connect in Preferences > Material Graph > Graph. This setting can produce shader compilation errors.

Toolbar Reports a Source Outside the Current Graph#

Cause: A connection targets a source prim that is outside the material or current NodeGraph scope, or the network crosses an incompatible render-context boundary.

Fix: Confirm that the correct context tab is active, then inspect the connected source path in the toolbar tooltip or Console. Reconnect the input to a node below the current Material or NodeGraph root. Unresolved Universal shaders authored below the current root remain visible and are reported as missing definitions instead of outside sources.

Cannot Disconnect from an Invalid Node#

Cause: When a node’s definition is missing, Material Graph reconstructs its ports from USD data. These ports might not support all interaction modes. Dragging from an invalid node’s port to disconnect it can fail.

Fix: Right-click the port on the valid (non-error) node’s side of the connection and choose Disconnect. This removes the connection without requiring interaction with the invalid node.

Catalog Is Empty#

Cause: The Catalog populates based on the currently selected render context and the configured module/definition sources. An empty Catalog usually means no sources are configured for the active context.

Fix:

  1. Confirm the correct context tab is selected.

  2. Open Preferences > Material Graph and verify the relevant plugin settings:

    • For MDL: check that Modules contains valid module paths.

    • For MaterialX: check that the definitions are not excluded by Ignored Contexts, Ignored Families, or Ignored Name Patterns.

  3. If the Show Catalog preference is disabled, re-enable it.

Texture Drop Does Nothing#

Cause: The dropped file’s extension is not in the accepted formats list.

Fix: Open Preferences > Material Graph > General > Droppable Texture Formats and confirm the file extension is present. Add it if it is missing, then retry the drop.

Solo Does Not Update the Viewport#

Cause: Context soloing is disabled when the Fabric scene delegate is enabled and the Kit major version is lower than 111.

Fix: Use Kit 111 or later, or disable the Fabric scene delegate. The Solo button displays a tooltip when this limitation applies.

NodeGraph or Backdrop Appears in the Wrong Context#

Cause: The Confine NodeGraphs to Context and Confine Backdrops to Context settings control whether NodeGraphs and Backdrops are filtered by render context. If these are disabled, those organizational elements can remain visible across contexts.

Fix: Enable the relevant confinement settings in Preferences > Material Graph > Graph to restrict visibility to the active context.

Known Limitations#

Limitation

Details

Context soloing with Fabric

Context soloing is disabled when the Fabric scene delegate is enabled on Kit versions earlier than 111.

Invalid nodes with missing definitions

Nodes with unresolved shader definitions display ports discovered from USD data. These ports support basic connections but can omit tooltips, type enforcement, and default values.

Polymorphic node resolution

Polymorphic MDL nodes require the source MDL asset to be accessible at resolve time. If the asset is offline or the module path is incorrect, the node cannot expand to its concrete variant.

Getting Help#

  • Toolbar indicators: Check the error and warning badges in the Material Graph toolbar. Hover over a badge to read validation details for the current graph.

  • Tooltips: Hover over nodes, ports, and connections for contextual information including data types, current values, and error descriptions.

  • Console panel: Open Window > Console to view the application log. Material Graph writes detailed error and warning messages that can help diagnose issues not visible in the graph UI.