Create a ticket

Q100391: Troubleshooting rendering issues in Katana


When you’re trying to start your first renders in Katana, you may hit some common issues that stop the render from producing the desired result. This article describes how to diagnose and solve issues such as:

  • The render fails immediately after starting

  • The rendered image is completely black

  • Renders will not start in Katana command line modes

  • Errors appear when rendering in a command line mode that do not appear when rendering in a UI session



The render fails immediately after starting

If the render fails right after it is started, it may be because there is no camera present in the scene or because no license is found for the renderer (this may happen specifically when using RenderMan). To troubleshoot, please inspect the render log in the Render Log tab in Katana, to see the error message and take the appropriate steps to solve the issue, for example by creating a camera in your scene or by referring to the renderer vendor's documentation to license the renderer plug-in.

Example render log output for missing camera:


Example render log output for missing RenderMan license:



The rendered image is completely black 

If your render completes, but the final image has only black pixels, a good first step is to check the Alpha channel of the image to see if the objects are actually rendered, but don't appear in the colour channels. To do this, hover over the Monitor tab and press A:


If the object shows up in the Alpha channel like in the image above, there are several possible reasons why it might not appear in the colour channels:

  • There is no material assigned to the rendered object. Some renderers will assign a standard material which will render in this case, while others will render a black image as there is no material that could define the surface properties of the rendered object.

    To remedy this, create a material using a Material node and assign it to the object you want to render, using a MaterialAssign node. To learn more about materials please see the Katana Online Help on Adding and Assigning Materials

  • There are no lights in the scene. If a material is assigned to the object, depending on which renderer is used the final image may not show any pixel data as there is no light interacting with the object. 

    To fix this, create a light using the GafferThree node and make sure it is pointing at the object to illuminate it. To learn more about creating lights please see the Katana Online Help on Lighting Your Scene.

  • The lights in the scene are too dark. If there is a light in your scene, the rendered image may still be black if the light’s intensity is too low to actually illuminate the object. 

    If this is the case in your scene, double-check that the light is pointing at the object you are rendering and try increasing the Intensity or Exposure of the light to make it brighter in your scene.


If the object does not appear in the Alpha channel, please check if the renderer you are using is configured correctly according to the renderer vendor’s documentation.


Renders will not start in Katana Batch or Script mode

You may wish to start a render in Katana’s command-line interface (batch, script or shell mode), for example using a command similar to the following:

katana --batch --katana-file=/tmp/clean.katana --render-node=Render -t 1

In this case you may experience the render failing to start with an error similar to the following:

[INFO MAIN]: Crash handling is disabled.
[INFO LicenseCheck]: Render License failed.
Timestamp: Thu Mar 29 11:52:36 2018
License(s) Requested:
katana 2017.1003 render only with options all
Extended Info: None Provided
Host : <hostname>
System ID(s) : <systemID>
RLM Environment Info: <RLMEnvironmentInfo>

Reason for failure: A suitable license does not exist.

katana_r : No license for product (-1)
License Path: <pathToLicense>

[ERROR MAIN]: No 'Render' license available.

This is due to Katana’s command line modes requiring a different type of license than interactive sessions. Please see this article for more details: Q100338: Differences between Katana interactive and Katana render licenses

If you want to render in a command line mode and don't currently have a Katana render license, please contact our Sales team at to discuss purchase options. 

Errors appear when rendering in a command line mode that do not appear when rendering in a UI session

If you have a valid render license for Katana, you may still hit the case of a scene that renders without issue in UI mode and fails to render in a command line mode. You may see error messages similar to the following:

[ERROR python.Nodes3DAPI.Node3D]: Error in incoming connection of node 'ground_mat1': Node "mat1" is not compatible with shading nodes.


[ERROR python.root]: An AttributeError occurred in "": Renderer 'prman' not supported.
    Traceback (most recent call last):
      File "python/Main\", line 367, in 
      File "python/Main\", line 313, in __main
      File "bin\python\Main\", line 96, in Main
      File "bin\python\Main\", line 450, in __setupOutputs
      File "bin\python\Main\", line 666, in PrepareOrDisconnectDependencies
      File "bin\python\Main\", line 618, in __prepareOrDisconnectDependencies
      File "bin\python\Nodes3DAPI\", line 142, in SyncOutputPorts
      File "bin\python\Nodes3DAPI\", line 1225, in GetRenderNodeInfo
      File "bin\python\Nodes3DAPI\", line 1254, in __init__
      File "bin\python\Nodes3DAPI\", line 1262, in __get_producer_data
    AttributeError: Renderer 'prman' not supported.

If you see this problem, please make sure that your command line environment is set up in the same way as the environment you’re launching your interactive sessions from. This includes making sure that all the necessary environment variables are set so Katana can load the renderer plug-in and associated components like shaders, etc.

For more information on launching Katana and setting environment variables, please see the following articles:

Q100272: Creating a Katana launcher script for Linux
Q100242: Creating a Katana launcher script for Windows



You might also be interested in the following content related to Katana rendering in our Knowledge Base:

Q100388: Glossary of rendering related terms in Katana
Q100091: Rendering multiple frames in Katana GUI mode
Q100370: Defining render passes using the RenderOutputDefine node
Q100356: Increasing preview efficiency with Interactive Render Filters
Q100341: Tile rendering in Katana
Q100384: Render fails when merging multiple channels AOVs in Katana via ExrCombine

Was this article helpful?

We're sorry to hear that

Please tell us why
1 out of 8 found this helpful