SUMMARY
Sometimes you may find an issue in Mari that keeps happening, or something is just not working as expected. For such situations that you'd like to address on your own, this article empowers you to become a great Mari troubleshooter. It offers an array of general troubleshooting tips which may help you learn more about your issue and tackle it.
MORE INFORMATION
Know the information you‘re looking for when investigating your issue
Keep in mind that there are many positive outcomes you can aim for when troubleshooting, such as:
- Finding a workaround that allows you to complete your task through different steps.
- Knowing exactly what setups should be avoided so that issues don’t reoccur.
- Removing the symptoms of a bug after triggering it.
- Recovering lost work.
- Sharing your findings with other people.
- A better understanding of Mari.
All of these outcomes require understanding the following aspects of your issue as well as possible:
- Steps to Reproduce - The specific order of actions that activate conditions and trigger the issue. These steps should be simplified and condensed as much as possible.
- Conditions - The individual circumstances required for the issue to occur, which are activated in a specific order in the steps to reproduce. Examples include a node attribute set to a certain value, an incorrectly used Preference, a third-party plugin, a corrupted file, or an incomplete OCIO Config.
- Trigger - Once all the conditions are met, the trigger is the action that has an unexpected behaviour.
- Symptom - On top of unexpected behaviours, some triggers may also result in changes to your work that can remain even after the conditions are removed, such as textures that are now corrupted.
Some of the tests suggested below will provide you with this information, which you can then use to troubleshoot and find a positive outcome. Meanwhile, other tests may directly fix your issue, from which you'll be able to deduct what was causing it.
Confirm that your computer supports Mari
It may be helpful to confirm that your computer fully supports Mari by comparing your setup to our requirements. This would be particularly relevant for performance, canvas rendering, and file I/O issues. Please see:
Mari’s System Requirements
Q100701: Supported operating system compatibility list for Mari
Search the Knowledge Base and the Bug Tracker for your issue
It may be that you’re experiencing a known issue, and a full investigation has already been performed by Foundry’s Support team. In this case, the information required to address your issue may already be available here in the Support Portal, and you can investigate using the search bars on the following pages:
-
Mari’s Bug Tracker - If your issue is a known bug, there will be a Public Bug Report that describes the issue, the exact steps that reproduce it, the Mari versions affected, and any known workarounds or solutions. From this information, you may find a solution that fits your individual needs. You can learn more about the Bug Tracker here:
Q100068: What is the Bug Tracker and how can you use it? - Mari’s Knowledge Base - Besides bug reports, Foundry’s Support Team also writes articles (such as this one) that can help you with various workflow and troubleshooting scenarios. Here you may find fixes and workarounds for specific issues, recommended best practices (which may indicate why your issue happened), how to recover lost work, how to improve performance, and much more.
Check the Known Issues section of the Release Notes
Mari’s Release Notes include a Known Issues section that lists any critical known bugs that we hope to address in upcoming releases, along with workaround suggestions where relevant. You can find the Release Notes for your Mari version here:
Mari’s Release Notes
Update Mari to get the latest bug fixes and feature enhancements
If you’re using an older version of Mari, it’s possible that your issue has been addressed through development in a later version, either through a bug fix or a feature enhancement. You can check which version of Mari is the latest and download it here:
Download Mari
Uninstall and then update or downgrade your GPU drivers
Issues in Mari can be caused by a faulty GPU Driver, especially when it comes to performance, textures, and the viewport. So you can try upgrading (or downgrading) your NVidia or AMD drivers, reopening Mari, and checking whether your issue is resolved.
For the most thorough GPU driver upgrade, you can first fully uninstall your current driver to ensure no problematic components are left behind. For this, you would use a tool such as Display Driver Uninstaller (DDU).
You can find DDU and the drivers for your machine on the following pages:
Display Driver Uninstaller - Download
Nvidia Drivers
AMD Drivers
Reproduce the issue at different safe mode levels
Our first practical test is to attempt to reproduce the issue, ideally from scratch, at different safe mode levels. If you find that the issue is no longer reproducible at a certain level, that may indicate where your issue is coming from. For example:
- If the issue stops occurring at --safe=4, the issue should be related to a Mari setting that isn't at its default, so perhaps you want to start looking in your Preferences or Tool Properties for the source of the problem.
- If the issue occurs at --safe=8 even in a new Example Project, then you have confirmation that this issue is inherent to Mari and most likely a bug (unless your Mari install has become corrupted).
While testing with the safe mode levels, keep in mind that it won't necessarily resolve a problem that was created by something you did in a normal Mari session. Whether it fixes an existing issue or not is a valuable peace of information. For example, imagine you triggered an unknown source issue that caused texture data to disappear from a Paint node:
- If the textures come back in safe mode, this means the symptoms are only visible while the trigger is active. Perhaps the issue is that the Canvas is failing to render your existing textures.
- If safe mode doesn’t bring back the textures, then the symptom can exist after the trigger has been removed, so perhaps the textures are now corrupted.
To learn what safe mode is, its different levels, and how to launch Mari with them, please refer to:
Q100022: Using safer mode to launch Mari as a fresh install
NOTE: If safe mode resolves your issue, the solution to your problem is not to always launch Mari in safer mode, as there would be various limitations to always launching Mari as if it were a fresh install. Instead, you must use the information safe mode provides to address the issue in regular Mari.
Checking whether the issue is specific to one project
Regardless of whether you're currently focused on resolving your issue or understanding your issue, knowing whether you are able to reproduce it in a different Project should give you some useful insights:
For example, if the issue is specific to your original Project, then maybe you have too many Bake Point nodes, or there’s something wrong with your UVs. On the other hand, if you can reproduce it easily in another Project, perhaps having a specific node setup isn’t relevant, or there’s nothing wrong with your geometry.
The best way to check whether your issue is project-specific is to try to reproduce it in Mari’s Example Project, as there are reassurances that come with testing on a complete archive that was set up correctly on a different computer. For some scenarios, it may also be worth testing on a brand new project with as little content in it as possible, in which case you could create your own test project using simple geometry.
To create a new version of the Example Project, open Mari and select Help > Create Example Project.
Combining safe mode with the Example Project
In the the above two sections, we described first safe mode and then the Example Project, and how to use each as a troubleshooting tool. Keep in mind that for most issues, your first test should be to try to reproduce the issue using the Example Project in safe mode. This is because performing these two tests together may indicate whether the issue is inherent to Mari, since you remove variables like third-party plugins and incorrect project setups at the same time. Once this test is complete, you can move on to trying each troubleshooting tool separately if needed.
Removing User Configurations
If your issue stops occurring at --safer=4, or you otherwise believe that it’s related to your user-defined configurations (such as your Layout, Preferences, Tool Properties, or Shortcuts) then you may want to try removing your config in order to reset Mari to its factory-default settings. It could mean losing all the ways in which you’ve personalised Mari, but it has been known to immediately resolve many issues such as incorrect tool behaviours, poor performance, and even crashes on launch.
To reset Mari to its default settings:
- With Mari closed, move or rename your TheFoundry folder. This prevents Mari from finding and loading your configs, but you get to keep a backup of them.
- Launch Mari. As Mari won't be able to find a TheFoundry folder, it will be recreated from scratch using default settings.
- See if your issue is resolved.
- If it's resolved but you’d like to restore some of your configurations, you can now try moving some of the files from your original TheFoundry folder back into the new TheFoundry folder in between Mari sessions.
- While doing Step 4, you will find that restoring a specific file brings back your issue. This should indicate the source of your problem, from which you can investigate further if you wish to. The culprit will often be the Mari7.1v1 file, so you could even try just removing this file in Step 1 and relaunching Mari before trying to remove the whole TheFoundry parent folder.
More information about Mari’s config folder and where it can be found is available here:
Q100723: Mari's user configuration files and where to find them
NOTE: You will most likely want to bring back the Shelves folder to restore your Shelf content, as this is valuable and typically not the source of any issues.
Read the MariLog file or the Verbose Output
The MariLog.txt file is a report that is generated while you’re working in Mari. It reports everything about what the application is processing, and it includes errors and crash reports. As such, it’s an invaluable resource when it comes to troubleshooting, as it may provide insights into the cause of your issue.
Reproduce your issue, open the MariLog.txt file, and have a read through the last few lines for any useful information. The following article provides more information on the MariLog.txt and where to find it:
Q100020: Mari's MariLog.txt file and where to find it
In some cases, it may be helpful to see the MariLog.txt output as it’s being generated live, to see how certain actions you take are being processed under the hood. For this, launch Mari with Verbose Output:
Q100589: How to launch Mari with Verbose Output to aid troubleshooting
Identify and reduce the steps and conditions
If you know a set of steps that consistently reproduce an issue, then you should be able to further isolate the exact conditions that trigger it. To do this, reproduce your issue repeatedly, but for each cycle do one of the following:
- Remove some steps and check whether the issue still occurs.
- For example, maybe you don’t need to be viewing a specific node in order to trigger a crash, so that step can be removed.
- Instead of steps, try to remove conditions.
- For example, if you’re getting a shading error when you view a Channel, remove certain sections of the upstream nodes until the shading error is resolved. This would help you identify the specific node causing the issue.
- Try to reproduce the issue by taking a different approach.
- For example, you could export a texture straight from a Paint node instead of using the Export Manager. If the issue doesn’t happen when you export from the Paint node, then perhaps the problem is not with general exporting, but with the Export Manager instead.
These are common troubleshooting techniques that allow you to identify what exactly is causing your issue. Once you know the exact conditions, it will be easier to avoid them. This may even help you resolve the issue by knowing where to address it (such as by changing a tool’s properties).
Through this troubleshooting method, you'll also be improving your description of any issues you find that should be reported to Foundry Support. As it's more likely that we'll be able to reproduce your issue with a clearer breakdown, it's also more likely that we'll get back to you with suggestions on working around the issue and a full report of any bugs you found.
Reinstall Mari
It’s possible that the issue you’re experiencing is caused by a faulty installation of Mari on your machine. This could lead to launching issues, missing features, data loss, and other problems. However, simply reinstalling Mari does not equate to achieving a “factory reset”, so it may not resolve these issues. This is because some content Mari uses is not removed from your computer by the app’s uninstaller.
The following article describes how to perform a thorough uninstall of Mari. Afterwards, get a fresh download of Mari’s installer from the second link and reinstall:
Q100138: Uninstalling Mari and all of its associated content
Download Mari
Discuss it with the community
Remember that you’re not alone, and it’s likely that other Mari users are familiar with the issue that you’re currently experiencing. Besides reaching out to Support, you can discuss your issue with other artists.
We have communities who are keen to share knowledge and make the most out of Mari together. These are great places to ask, troubleshoot, and discuss anything related to Mari and texturing.
We have an official Mari Community forum, which can be found here:
Foundry Community - Mari Artists
There is also a thriving Mari Discord group. Join it here:
Discord Invite Link
FURTHER READING
Depending on your issue, you may also find the following articles helpful:
- Q100081: Troubleshooting different types of Mari issues
- Q100041: Mari launch issues
- Q100188: Improving performance in Mari and in specific Projects
FURTHER HELP
If you are still experiencing difficulties or if you have identified the steps to reproduce a bug, please create a support ticket and provide us with the information requested in this article:
Q100090: Information to send Support when reporting a Mari issue
For more information on how to open a Support ticket, please refer to this article:
Q100064: How to raise a support ticket
We're sorry to hear that
Please tell us why