Troubleshooting

Look up your symptom as it is. Most of the time there is one cause. If a higher value is 0 or off, every value below it is ignored.

Installation · Conversion · Setup Wizard · Shadows · Depth effects · Outline · Face · VRChat · WARUDO · Performance · Bake and restore

No value has any effect

Check in order from the top.

1. Turn on All Effects. While it is off, every section is disabled.
2. Turn on that section's master toggle. While it is off, Quick Settings appends (Module Off).
3. Raise that feature's higher value from the table below.

What is missing	The higher value to check first
Base tint	Tint Blend Strength
The whole surface is too transparent or too opaque	Base Map Opacity
Depth Rim Light · Depth Shadow	Master Width, then each module's intensity
PBR highlights and environment reflections	Specular Intensity
Extra texture layers	Surface Stack Layer Count
Normal map layers	Normal Layer Count
MatCap layers	MatCap Layer Count
The shadow boundary band	Boundary Width, then Boundary Intensity
Shadow pattern	Pattern Intensity
Face normal correction	Proxy Normal Intensity
Face area mask	Mask Intensity. At 0 the whole material counts as face
Channel settings of the PBR packed mask	Use Packed Mask
Cast shadow brightness and blending	Receive Intensity
Alpha mask	It is invisible even when on if the surface mode is Opaque (2000)

Installation

Materials look pink (magenta)

Cause	Action
Render pipeline mismatch	Swap to the matching backend shader
Below shader model 4.5	Run StudioRaming > MingToon > Validate Project. PC only is supported
URP version out of range	Match Unity 2021.3 + URP 12.x

In this case no error message appears at all

The whole SubShader drops out, so the log stays quiet. Pink is the only signal.

Validate Project flags the Unity version

Code	When it appears	Meaning
MING-ENV-UNITY-VERSION (error)	The editor is neither 2021.3 nor 2022.3	An unsupported stream
MING-VRC-UNITY-VERSION (warning)	The VRC SDK is present but it is not 2022.3	This project has no avatar upload support
MING-ENV-BUILD-TARGET (error)	The build target cannot meet shader model 4.5	Android, Quest, iOS, WebGL. Switch back to Windows

2022.3.22f1 is a fully supported version, so nothing is flagged. → Validate Project Codes

A progress bar appears right after install or update and the editor is slow

MingToon is precompiling shader variants. It is not an error. → Wait for the first compile to finish

Symptom	Meaning and action
The MingToon warm-up progress bar is showing	Wait until it finishes. It is done when the numbers are full and the bar disappears
You pressed Cancel and the compile keeps going	It closes only the bar. The compile moves to a Unity Progress item and keeps going; watch its progress and cancel it in the status bar at the bottom right of the editor. If you cancel there, what was finished until then stays recorded
The editor stalls for a moment the first time a material is drawn after cancelling	Unity compiles the remaining variants at the moment that shader is first drawn
The compile starts again	The shader source, the Unity version, or the graphics API changed, or you deleted the project's Library folder. The record is in Library/StudioRaming/MingToon.warmup
No progress bar after a VCC update	Valid markers/pass caches let MingToon skip requests. VPM schedules a background Progress item, so also check the status bar. Unprepared combinations compile on their first draw. Public-package installation/update acceptance is a separate check

The installer window says “Installation stopped … Unable to remove the file to be replaced”

The installation has finished, but this message can appear if another program, such as antivirus software, briefly holds the installation record file open at the moment it is rewritten. Click Recheck installed package in the installer window once. If the message changes to “The exact MingToon VPM package and migration journal were verified after reload.”, the installation is fine. If the same message persists, do not import again; contact support with a screenshot of the error.

A file replacement error appears when starting an update from 0.1.11

If “Unable to remove the file to be replaced” appears when starting an update from 0.1.11, click Check Installation State, then Check for Updates to query again, and retry the installation. If the same error persists, do not keep repeating the installation. Back up the project and contact support with a screenshot of the error. Publishing a new version alone cannot be guaranteed to eliminate this intermittent error in the older version.

The button sequence above applies to the 0.1.11 update window.

The update window has only one button

The current window checks the latest information on opening and uses one Update button for installation, checking a failed state, or refreshing. Lower versions are not offered as new updates. Back up, convert a new copy from the original materials, and compare with the previous result. → Installation and updates

I switched the render pipeline and every material broke

The switch dialog converts the project's MingToon materials to the matching backend in bulk. If you miss the dialog, you can run it again from the warning in the material inspector.

Why the switch is blocked	Action
The material is contained in another asset	Extract it from the sub-asset
The material is inside a read-only package	Copy it outside the package
The material is read-only or not checked out	Clear read-only or check it out

Materials in closed scenes and AssetBundles cannot be inspected. Open them separately and convert.

Conversion

A Factory look reports incompatible properties

Version 0.1.12 removes 105 obsolete mask-channel entries from 15 Factory looks to fix blocked application. Check that the installed presets and current version belong to the same package. This does not ignore unknown custom-preset properties and apply only part of a preset.

The look differs from the source after conversion

Read the lossy and unsupported items in the conversion log first. Then compare mask channels and inversion, and texture Tiling and Offset. Also check that AO, surface mode, and the face material decision match the source. → Reading the Conversion Report

If you made it with the Setup Wizard, the same report is under Conversion details on the done screen. The copy is separate from the original, so you can compare it side by side with the original materials.

Conversion or baking fails

Message	Action
No convertible material slots were found	Check where MingToon Manager sits, then Refresh Child Renderers
The MingToon source shader was not found	The installation is incomplete. Reimport the package
The generated shader could not be imported	Check write permission on the project folder and retry
The generated shader has a compile error	Check that the MingToon include folder is in its original path
Multiple MingToon Managers are selected	Select only one at a time

Setup Wizard

The wizard makes a copy without changing the original. The screen order and step-by-step explanation are in Setup Wizard.

The wizard does not open

Situation	Action
In Play mode	End Play and open it again. In Play mode the wizard does not open and makes no copy
You added MingToon Manager with Add Component in the Inspector and it did not open	That route opens it automatically only right after you newly add the Manager. A Manager that was already in a scene or prefab when you opened it, or one that came back through Undo or Redo, does not open it. Right-click in the Hierarchy and press MingToon > Convert to MingToon...
This object already has an open setup wizard.	Finish or close that target's wizard first
You selected a prefab with a Missing Script in the Project window	The wizard appears below the importer header in the Inspector

A red notice appeared

Find the sentence exactly as shown on screen in the table of When it fails. In every case the original is unchanged. If it fails before the copy prefab is saved, only the new folder created this time is deleted.

The done screen says Converted slots: 0

Nothing was converted. Open the wizard again and check Object to convert on the first screen. If N in Slots to convert: N is 0, the wrong target was picked.

The face is not drawn like a face

The wizard does not guess a face from names. If you leave the face mesh empty, only the face flag the source material itself declares is read and everything else stays Regular. In the Materials to convert list of the Look step, change that slot to Face and create the copy again. For a copy you already made, change the role under Review & edit role assignments inside 1. Assign face & skin renderers in the Convert / restore existing target section of the Manager's Start tab.

The copy is pink (magenta)

A render pipeline mismatch or a shader model below 4.5 is the usual cause. Check the "Materials look pink (magenta)" table under Installation.

I pressed Undo and the folder and files are still there

That is normal. Only placing the copy in the scene and switching off the original are undone together in one Undo. The created <name>_MingToon folder, prefab and material files are not removed by Undo, so delete them yourself if you do not use them.

The lighting menu (MLC) did not go into the copy

The step appears only when Ming Light Controller is installed. If the avatar's parameter usage cannot be read, or even the smallest menu does not fit in the space left, it is not added. The messages and actions are in the MLC step.

Shadows

Only the overlapping areas are pure black

Turn on Enable Unified Shadow in the Shadow Color section. Form, cast, and depth shadows collapse into one color. → Light and Shadow

It is normal for individual shadow colors to stop working after you turn it on. The values remain, so turning it off brings them back.

Cast shadows are blotchy

Location	Action
Cloth folds and the body in general	Turn on Suppress Self Cast Shadow and set Self Shadow Caster Bias between 0.01 and 0.03
The boundary is stair-stepped	Turn on Enable Projection Feather and adjust Projection Feather Radius · Projection Feather Intensity
Shimmering overall	Check the light's shadow map resolution, bias, and cascades in that order
A character shape overlaps the body in backlight	Turn on Suppress Backlit Silhouette

Feathering cannot bring back information that is not there

Detail that was never in a low-resolution shadow map does not return when you soften it.

No shadow pattern is printed at all

Cause	Action
Use Shape Tile is on but the tile slot is empty	An empty slot reads as white, and no density can cross white. Use a bundled tile
Pattern Intensity is 0	Raise it
The target does not match	Check Pattern Target
Dots do not react to tone and stay the same size	You loaded a binarized dot picture. A tile must be a threshold map

The character crushes to black in a dark world

Raise Preserve Base Map Color, Minimum Final Brightness, Indirect Light Lift, and Cast Indirect Lift in that order. If it blows out to white in a bright world, lower Maximum Final Brightness.

Depth effects

Depth Rim Light or Depth Shadow is not visible

Cause	Action
All Effects or Depth Effects is off	The inspector shows a button to turn it on
Master Width is 0	Raise it
Each module's intensity is 0	Raise it
The surface mode is Transparent (3000)	Change it to Semi-Transparent (2499)
Camera Depth Contribution is off	Turn it on
The ordinary VRChat screen	An avatar cannot force it → VRChat
URP	Install the Renderer Feature and enable Depth Texture
WARUDO	Install the Depth Bridge → Warudo

If the inspector says the depth texture is not ready, follow that guidance. If raising SSAO Radius does not widen it, you have hit the limit. The range is 0.001 to 0.05 m.

Only the inner outline disappeared

Enable Inner Depth Edge is in the Inner Outline section. That section is inside the Screen-space Effects group.

Cause	Action
Apply to Inner Outline is on and the vertex color is black	Turn the toggle off, or change Pressure Source
The surface mode is Transparent (3000)	Change it to Semi-Transparent (2499)
No camera depth	See the item above

The normal outline is drawn without depth. If only the normal outline is visible, the problem is depth.

Hair shows through the cheek

Change the surface mode to Semi-Transparent (2499). This mode blends alpha while still writing depth.

Transparent Depth Prepass is for Transparent (3000) only. Turning it on in Semi-Transparent (2499) changes nothing.

Outline

The whole normal outline disappeared

Cause	Action
The vertex color is black and Pressure Source is VertexRed	Change the pressure source or check the vertex color
Pressure Contrast is 0	Pressure is ignored completely. Raise it
Color Mask is 0	Return it to 15
Outline Master is off	Turn it on. The inner outline uses this gate too

The outline breaks at sharp corners

Normal Source is VertexColorTS or UV8TS on a mesh with no baked smoothed outline normals. Change it to MeshNormal. → Outline Smooth Normals UV8

I cannot paint outline thickness in the Scene view

The inspector tells you the reason in a sentence. The action for each message is in Painting directly in the Scene view.

I painted and the result got worse

If Pressure Source is Vertex Red and Normal Source is VertexColorTS, they overwrite the same channel. Change the pressure source to Vertex Alpha, or move the outline normals to UV8.

If other objects changed too, several renderers share the same mesh asset. Duplicate the mesh, assign it to that renderer only, and paint again.

Face

I painted the face mask and it does not work

If Mask Intensity is 0, the mask is ignored and the whole material counts as face. Raise it above 0. The mask priority is texture, vertex paint, proxy, then whole material. → Face shading

There is no shadow on the face at all

If Depth Availability is Force Off, Depth Shadow is never drawn. The automatic face correction removes projected shadows from the face. Turning on Projected Shadow When Depth Off on the Face material falls back to projected shadows when depth is absent.

VRChat

I uploaded and optimization does not seem to have run

1. Check that the Unity version is 2022.3.22f1. The VRChat hook does not compile on 2021.3.
2. Check that the Console contains [MingToon] VRChat build hook compiled and registered.
3. In the Prepare for upload section of the MingToon Manager's Start tab, look at the Optimize On Build / Upload (Applies To Everything): On line. If it says Off, press Change in Optimize and turn it on in the Optimize tab.
4. Open StudioRaming/MingToonOptimizeReport.txt next to the project folder.

→ Checking that it ran

I can see depth effects but others cannot

That is the default. Depth effects are visible only to you and your friends. Turning on Show depth effects to non-friends in the Prepare for upload section of the Start tab of Manager shows them to everyone. In exchange, the load on the other person grows. This toggle appears only in a Unity 2022.3 project that has the VRChat SDK.

Not appearing in mirrors is also intended. It stops a mirror from using someone else's silhouette as a shadow. → How far depth effects are guaranteed

WARUDO

Every depth effect is empty in WARUDO

The Depth Bridge is not installed. Check the Playground path, the .cs extension, and the installed log. → WARUDO Depth Bridge

If only the main screen is correct and the Spout or NDI output differs, check that camera's depth enabled for camera= log. No log means the camera was not processed.

Performance

The inspector is heavy while I work

That is normal. The authoring shader compiles and keeps every feature and the maximum layer count at once. Because of that, you do not wait for a compile each time you turn a feature on. The trade-off is that inside the Unity editor the same material costs about twice the GPU time of the built result (measured). Do not judge avatar weight from editor frame rate or profiler numbers. Lightening is applied only at build time.

People say my avatar is too heavy

Turning every depth effect off also drops the depth light from the build automatically. That is the lightest path. → VRChat depth light

Bake and restore

The restore button on a baked material is disabled

Check that the bake Manifest is still there. The GUID of the original authoring material must also be alive. Also check that the Renderer hierarchy and material slots are unchanged since the bake. → Manual Bake and Restore

A feature I turned on after baking does not work

Features that were off at bake time and were not found as preservation targets are removed from the code. Mark values you will turn on later from a script with Keep Editable At Bake.

If this still does not solve it

Post the following in the bug report channel of the official Discord server.

1. Unity version and target platform (VRChat PC / WARUDO / general Unity)
2. Render pipeline (BRP / URP 12.x)
3. MingToon version
4. The full Console log
5. Steps to reproduce