Frequently Asked Questions and Troubleshooting

Below are some of the most common questions about Mari. If your question isn't answered here, review the documentation and the release notes or contact Foundry's customer support for help.

I can’t see or bake what I've painted.

There can be several reasons for this:

Paint Opacity has been set to 0 in the Painting palette.

A mask is preventing paint from appearing. Check if any of the masks are enabled in the Painting palette.

Project On has been set to Selected Only in the Painting palette, but you haven't selected any objects, patches, or faces. Either select the areas where you want paint to appear or set Project On to All.

The paint is on objects, patches or faces that have been locked. To unlock them, click Selection > Unlock Selected, Unlock All, or Unlock Entire Object.

The paint blending mode (Painting Mode in the Painting palette) has been set to a mode that does nothing to your textures. For example, if your texture is white, the paint is red and Painting Mode has been set to Hue, the paint is not visible.

Brush Opacity has been set to 0 in the Tool Properties palette.

Brush Flow has been set to 0 in the Tool Properties palette.

The paint buffer has been moved off the screen. To reset the buffer to its defaults, click Reset under Paint Buffer in the Painting palette.

My object has disappeared from the canvas.

The object may have been moved off the screen. Try pressing A or F to bring it back.

Mari’s bake behavior seems strange.

In the Painting palette, you can set whether Mari bakes automatically when you change the view, and whether the buffer clears automatically once you bake. Set Bake Behavior to:

AutoBakeAndClearMari automatically bakes and clears the buffer when you move the model.

Manual – You have to bake manually; and when you do, the paint stays in the paint buffer until you manually clear it.

ClearOnly – You have to bake manually; and when you do, the paint buffer clears automatically.

Mari seems slow when using the Clone Stamp tool.

When cloning from a particular channel, the Clone Stamp tool takes a “snapshot” of that channel as it appears on the screen and uses that as the source. As a result, the resolution of the cloned texture can depend on the current display resolution within Mari. Higher display resolutions produce better cloning results, but can dramatically slow Mari's performance.

Increasing the Paint Buffer Size or Resolution and Layer Count can affect Mari’s performance.

Increasing the Buffer Size or the Resolution and Layer Count, even when your graphics card supports large textures, can slow Mari’s performance. Adjust the Buffer Size under Paint Buffer in the Painting palette, and the Resolution in the Mari Preferences dialog under GPU > Virtual Texture.

Displacement preview performance seems slow.

If you have allocated a channel to be used in a Displacement shader component, the Type under Edit > Preferences > GPU > Virtual Texture, should be set to at least Half for more precise displacement. In addition, the channel containing the displacement map should be set to at least 16-bit. Please note that using values higher than these may reduce preview performance.

Mari keeps highlighting anything I've selected with a selection color. How can I turn this off?

You can configure the way Mari highlights selected areas. Right-click on the canvas and select Display Properties. Under Selection, adjust Fill Render and Outline Render.

I can’t find a Save As option.

Mari currently has no Save As functionality. You can, however, duplicate your project by right-clicking on it in the Projects view and selecting Copy.

If you want to pass your project on to another user, you can also select the project in the Projects view and click Archive. This creates an archive (a .mra file) that contains your project and all the textures and models associated with it.

If you use . (full stop) to separate parts of the file name (for example, "test.file"), Mari does not add the file extension .mra automatically. This allows you to use a different extension if desired. However, in most cases you most likely want to add the .mra extension to ensure the file is clear.

I want to bake what I’ve painted, but I can’t find the bake button.

The bake button sits at the bottom right of the workspace. It only appears when you have unbaked paint in the paint buffer.

You can also press B to bake.

Clicking on another application caused the floating palettes in Mari to disappear.

This is not a problem in Mari but caused by your Linux window behavior settings. To fix this on KDE 4, for example, you can:

1.   Go to Settings > System Settings > Window Behavior > Advanced.
2.   Uncheck Hide utility windows for inactive applications.

I am having problems with my Wacom tablet.

We have found that these links have been useful in solving the problems for some of our users:

On Linux, pressing the Ctrl/Cmd, Alt, or (Windows) shortcut key doesn’t do what it should. Instead, it does something else, like moves the entire Mari window.

This is usually caused, not by a problem in Mari, but rather by your Linux window manager, which is using one of these keys as a global shortcut. Depending on your window manager, you may be able to block the global shortcut, or select which of the three keys is used as the global shortcut. For example, if the Mari shortcuts you often use require you to press the Alt key, you can set the global shortcut to be the Windows key instead. This way, the Mari shortcuts that don't work are limited to those that require the Windows key.

To block the global shortcut on a per-application basis (that is, for Mari only) on KDE 4, you can:

1.   Right-click on the Mari title bar and select Advanced > Special Window Settings. This may open an information dialog where you need to click OK.
2.   Go to the Window tab.
3.   Click the Detect Window Properties button and then click on the Mari window.
4.   Make sure that Use whole window class and Match also window title are checked and click OK.
5.   Go to the Workarounds tab.
6.   Check Block global shortcuts, select Force from the dropdown menu, and enable the checkbox on the right. Click OK.

To select which key is used as the global shortcut on KDE 4, you can:

1.   Go to Settings > System Settings > Window Behavior > Window Actions.
2.   Under Inner Window, set Modifier to the shortcut key you need the least in Mari or other applications you use (for example, the Windows key).

This allows you to use the other two keys (in this case, Ctrl/Cmd and Alt) in Mari.

On Windows, pressing the Windows shortcut key should open the Start menu. This doesn’t happen when Mari has focus. Why is that?

This is because the Windows key is a shortcut key in Mari. Whenever Mari has focus, the Windows key is reserved for Mari, so that you can use all the Mari shortcuts.

If you need to access the Start menu, you can either click it manually or move focus to another application and then press the Windows key.

Pressing the Alt Gr key does not trigger the same shortcuts as the Alt key. Why is that?

The Alt Gr key is defined differently on the Windows and Linux operating systems. Due to this, Mari cannot determine what the Alt Gr key is intended to be linked to. If a shortcut lists the Alt key as part of the controls, this does not include Alt Gr as an alternative. For this reason, it is advisable to avoid using the Alt Gr key in your custom shortcuts.

On Windows, I’ve removed a drive from Mari’s file browser bookmarks. How do I get it back? Is it possible to delete a drive from the bookmarks permanently?

All logical drives that Windows can see are automatically added to Mari’s file browser bookmarks when you start Mari. You can remove these while Mari is running, but the only way to get them to reappear is to relaunch Mari. At present, you can’t delete a drive from the bookmarks permanently - it always reappears when you relaunch Mari.

Mari also automatically adds mapped network drives to its bookmarks. You should not disconnect a network drive while Mari is running and then attempt to reference files from that drive in Mari, as that may result in undefined behavior.

Generally, I need the channel to have precision when I paint in a linear colorspace, and I use 16-bit channels if I apply the gamma after the paint has been applied. Now that colors are linearized before baking, do I need to use HDR mode for my paint to be applied without artifacts or can I paint in a linear colorspace but with 8-bit channels?

When working with 8-bit (byte) channels in a non-linear colorspace, it is recommended that you set the virtual texture's type and paint buffer's color depth to 16-bit (half) or 32-bit (float). This keeps the project's data footprint down but the data is still converted to floating point and linearized on upload to the GPU for painting, this way it keeps the colorspace transform error down to a minimum. When Mari bakes paint and texture data back into the channel, the inverse is applied, so the floating point data is color corrected and converted back to 8-bit (byte).

If you want to eliminate errors as much as possible, it is recommended to use floating point channels and then export to the colorspace and bit-depth of your choosing. However, this means the project is a lot larger and performance might be an issue on a less capable machine. It is not possible to eliminate all the errors even if using full 32-bit float everywhere as you still get floating point and interpolation errors being introduced.


Advanced Debugging Methods

If you are launching Mari from the command line or terminal, you can run the application in one of two safe modes: --safe and --safer. These safe modes run a number of options, described in theSystem and Hardware Requirements

If you prefer, you can choose instead to run individual safe mode options rather than those grouped under --safe or --safer. To do this, type the given number for the option after the --safe command. Please be aware that these work on an "up to and including" fashion, so selecting --safe=3 also runs --safe=1 and --safe=2 (effectively, operating the same as running the --safe command).

Safe Mode

Corresponding Safe Feature

--safe=1 Disables startup Python scripts.
--safe=2 Disables user custom plug-ins.
--safe=3 Bypasses user Python libraries.
--safe=4 Bypasses user settings.


Bypasses user environment variables.


Disables any Python scripts in the Mari installation that have been tampered with.


Disables any Node Graph nodes in the Mari installation that have been tampered with.


Forces the nuke-default OCIO colorspace configuration.

Warning:  If your project's OCIO config file(s) differ from the one specified in --safe=8 mode, the colorspace data changes permanently. It is highly recommended that you archive your project before opening it in --safe=8 mode.