Troubleshooting

Each problem here is named by what you see. Read the cause, then follow the fix. If a warning or an error shows in the inspector or in NDMF's console, look it up in Messages first: every message has its own entry with what to do.

My blinking or lip sync stops while a toggle is on

Likely cause

The toggle holds a shape that VRChat uses for blinking or for lip sync. While the toggle is on, AvatarDoc pauses VRChat's blinking or lip sync so that the two do not fight. They come back when the toggle is off. This happens with a Hold the rest rule that has Hold blink or Hold visemes turned on, with a Pin row on an eyelid or mouth shape, and with a trigger whose effect moves such a shape.

Fix

1. In the tree, select the toggle or the trigger.
2. In its Blendshapes section, find the rule line under the rows. Turn off Hold blink to keep blinking, and Hold visemes to keep lip sync.
3. If a row sets an eyelid or a mouth shape on purpose, the pause is the expected result. To keep blinking, remove that row.
4. If blinking still stops after an upload, look for a warning that says blinking or lip sync is left to another system. A sleep or AFK layer of your avatar then owns it. See the message.

How the pause works: Blinking, lip sync and face tracking. The controls: Hold the rest of a face.

Still stuck

See Report a bug.

A toggle never turns off, or something stays changed after I turn it off

Likely cause

Something else writes the same object, shape or material after the toggle does. These are the usual ones:

• Two controls change the same thing. The one built later wins: later menu entries first, and triggers after every menu control. An override wins over every control.
• A preset, or a contact in Flip mode, changes the toggle's own parameter and turns it on again.
• A blend shape row is set to Pin. While the toggle is off, a Pin row writes nothing. When the toggle turns off, and when the avatar loads, it sets the shape back to its value in the scene once, unless another layer owns the shape, and from then on whatever else moves the shape decides it.

Fix

1. Select the toggle. If its row has a problem chip, hold the pointer over it. A note that says the target is changed by more than one control names the other controls. See the message.
2. Give each control its own targets, or put toggles that exclude each other in one exclusive group, as in Make one-of-many choices.
3. For a blend shape that should return to its scene value, set the row to Fixed. A Fixed row writes the scene value while the toggle is off.
4. Check the presets and the contacts in Flip mode: one of them may write the toggle's parameter. See One button for several settings and React to touch.
5. Test in Play mode with Gesture Manager, and switch the toggle off. See Your first toggle.

Still stuck

Press Summary in the header and keep the text for Report a bug.

My menu, or a toggle, is missing in VRChat

Likely cause

AvatarDoc built the avatar without that control, or put it where you did not look. These are the usual causes:

• The AvatarDoc component is switched off. AvatarDoc skips a component that is switched off, and the tree shows its rows with a disabled chip.
• The toggle has In menu turned off. It has no button then, and the row has a no menu chip.
• The entry is built for the other platform only. Its row shows a PC only or Quest only chip and is dimmed.
• The component installs into a submenu with Install into, so the button is inside that submenu and not on the first page.
• A page held more than eight controls, so the rest went onto a More page.
• An error stopped the build. An error stops the upload, so the avatar you see in VRChat is an older one.

Fix

1. Select the object that holds the component, and check that its checkbox in the inspector is ticked.
2. Look at the tree: it shows the menu as it will be built, with the submenus and the More pages. Find your control there.
3. Open Component settings and check Install into and Platform.
4. Select the toggle and check In menu and its Platform.
5. Upload again, and read NDMF's console for errors. Messages explains each one.

Still stuck

See Report a bug.

The upload stops: the synced parameters need more bits than VRChat allows

Likely cause

VRChat gives an avatar 256 bits for synced parameters, and the avatar is over. A synced toggle costs 1 bit. A synced exclusive group or a synced radial costs 8. With VRCFury installed, the same check is only a warning, because VRCFury makes the parameters smaller at upload.

Fix

1. Read the memory bar in the inspector's header. It shows the avatar's own bits, the bits AvatarDoc adds and the bits that are free.
2. Turn off Synced on toggles that other players do not need to see. They then cost nothing.
3. Put toggles of one kind into an exclusive group. A group costs 8 bits however many toggles it holds.
4. Take the menu items of the avatar that you never use out of the build with Remove from avatar. That frees their parameters.

Fit in VRChat's parameter memory goes through these in order. How the count works: Parameters, sync and memory.

Still stuck

See Report a bug.

My menu has a "More" page that I did not make

Likely cause

VRChat shows at most eight controls on one page. When a submenu holds more, AvatarDoc keeps the first seven where they are and moves the rest onto a More page that takes the eighth place. The tree shows these pages as More (page 2), More (page 3) and so on.

Fix

1. Select the submenu. A row with 8 of 8 is full.
2. Move some of its controls into a submenu of their own: drag them in the tree.
3. Check the tree again. The More page goes away when everything fits.

See Organise the menu and the message.

Still stuck

See Report a bug.

A toggle works on PC, but it is missing or wrong on Quest

Likely cause

AvatarDoc builds for the platform that the editor targets. An entry that is set for PC only is not built for the Quest copy of the avatar. Or the two copies have different parameter lists. VRChat syncs parameters by their place in the list, so a list that differs shows the other platform's players the wrong toggles.

Fix

1. Check the build target of the project: Android and iOS count as Quest, everything else as PC. The line under Platform in Component settings names the platform the editor builds for.
2. Select the toggle and open its Advanced fold. Check Platform.
3. Do not delete an entry from one copy of the avatar. Set its Platform instead, because then it keeps its parameter in the same place.
4. If a warning says the parameters differ at a position, rebuild both copies from the same menu order. See the message.

Different setups for PC and Quest shows the settings.

Still stuck

See Report a bug.

A toggle I converted behaves differently from the original

Likely cause

AvatarDoc does not carry over everything from VRCFury or Modular Avatar. The Convert window lists a note for each part that was left behind. These are the usual differences:

• A transition animation, a security lock, a separate state that only you see, a hold button and an inverted rest logic are not carried over.
• An AvatarDoc toggle switches at once, or fades with Blend time.
• The entry gets a parameter of its own. An outside tool that set the old parameter, such as an OSC app, must set the new one.
• A hand made layer that rested somewhere else is not converted at all: the window lists it with its reason.

Fix

1. If you have not changed anything else yet, use Edit > Undo. Convert undoes in one step.
2. Open the Convert window again and read the notes of the row. What each note means explains every one.
3. After you convert, select the new entry and check its Off value fields, Blend time and parameter name against the old toggle.
4. To keep the old behaviour, leave that item as it is, with Keep as it is in the Convert window.

See Convert from VRCFury or Modular Avatar.

Still stuck

See Report a bug.

A piece of clothing keeps the wrong body shape, or two pieces fight over a shape

Likely cause

Two AvatarDoc Shapes pieces hold the same shape, and different layers switch them: two toggles, or a toggle and a trigger or a merged animator. The later layer decides the shape. While the later piece is on, its value holds. While it is off, the shape goes back to rest, even when the other piece is on. A piece that nothing switches loses to one that is switched.

Fix

1. Read the warning. It names both pieces and the shape. See the message.
2. Put both pieces on one toggle, or put their toggles in one exclusive group. Then one animation switches both, or only one piece is on at a time.
3. If a note says nothing turns the object on, add a toggle or an outfit set for it, or take the component off the piece.

AvatarDoc Shapes lists what decides the winner.

Still stuck

See Report a bug.

Hold the rest does not hold a shape

Likely cause

A rule holds only the shapes that something else moves. It leaves these shapes to something else:

• the shapes the entry has rows for, and the shapes a toggle's own animations move
• the shape a blend shape trigger follows, and the shapes an AvatarDoc Shapes component drives
• the blink and mouth shapes, unless Hold blink or Hold visemes is on
• a shape that only something outside your avatar moves, such as a dance in an MMD world

Fix

1. Select the toggle and open the rule line under its rows. Its note says how many shapes it can hold, up to.
2. To hold the eyes or the mouth too, turn on Hold blink or Hold visemes.
3. For an MMD world, use the world's own settings. AvatarDoc holds only what the avatar's own animations move.
4. If an error says only a toggle or a trigger with effects can hold the rest, move the rule to one of those. See the message.

See Hold the rest of a face.

Still stuck

See Report a bug.

A touch or PhysBone trigger never fires

Likely cause

For a contact, an error at upload names the cause:

• no object is set for Anchor
• no tag is ticked under Touched by
• both Self and Others are off

For a PhysBone trigger, no PhysBone is picked. A trigger that flips a toggle does nothing on a platform where that toggle is not built.

Fix

1. Select the trigger and read the messages on its panel.
2. Set Anchor, tick at least one tag under Touched by, and keep Self or Others on. The default is Finger and Hand, and both switches on.
3. For a PhysBone trigger, pick the PhysBone in PhysBone.
4. Touch the sphere with the test hand: press Test with a hand in the trigger's panel, as in Try it with a test hand. If the hand fires it, test the touch in Play mode with Gesture Manager's Clickable Contacts, or in VRChat.

See React to touch and React to PhysBone grabs, poses and stretches.

Still stuck

See Report a bug.

A trigger with conditions never fires

Likely cause

The trigger has no condition, or a group with nothing in it, or it reads a parameter that the avatar does not declare. A parameter that nothing declares is treated as a Float, so a condition made for a whole number or for true or false may not work.

Fix

1. Select the trigger. Under When, check that at least one condition is set.
2. Remove a group that is empty, or add a condition to it with + And.
3. If a warning says nothing declares the parameter, add it under Parameters with its real type. See the message.
4. Check Only while: the trigger fires only while that toggle is in the state you chose.

See Link effects to another toggle or a parameter.

Still stuck

See Report a bug.

A gesture face does not show with face tracking

Likely cause

• The face is set to Paused in the Gesture faces window. While face tracking is on, a paused face changes nothing on purpose: face tracking has the face.
• Face tracking names a parameter your face tracking setup does not set, or one it sets the other way round, so AvatarDoc thinks face tracking is on all the time.
• The parameter is the Lip Tracking toggle of the VRCFT face tracking templates, LipTrackingActive, which is saved: left on while you play without face tracking, it keeps every face set to Paused off.
• Other players see a face set to Paused while you do not: the parameter is not synced, so to them face tracking is never on. The window says so under the field.
• Face tracking moves different shapes than the face does, so both show at once and the face looks wrong rather than missing.
• The face does show, but face tracking takes the shapes back the moment you let go of the gesture. That is how a face set to Wins ends.

Fix

1. Select the object with the AvatarDoc component and press + Gesture faces in the toolbar.
2. In the gesture's row, set While tracked to Wins if the face should show over face tracking while you hold the gesture.
3. Check Face tracking: it must name the Bool parameter that is on while face tracking is on, such as LipTrackingActive, synced if your setup has one. Pick it from the list beside the field, type its name, or empty the field for None when the avatar has no face tracking.
4. Playing without face tracking: switch the Lip Tracking toggle of the face tracking menu off in game, so the faces set to Paused show.
5. To keep face tracking from moving the face's other shapes while a face shows, give the face's trigger a Hold the rest rule: select the trigger in the tree and press Hold the rest in its Blendshapes section. See Hold the rest of a face.
6. Press Make gesture faces, upload, and test with face tracking on.

More about the choices: Gesture faces window.

Still stuck

Press Summary in the header and keep the text for Report a bug.

A blend shape trigger does nothing

Likely cause

The trigger follows a shape, and nothing in the avatar's FX animator moves that shape. Or VRChat moves the shape itself, as it does for blinking and lip sync, outside every animation, so the trigger never sees it move. Or the shape moves in a Gesture or Action animation, outside the FX layer. Or the trigger has requirements in several cards: it reads only the card its shape is in.

Fix

1. Read the warning on the trigger. It names the shape. See the message about no FX animation and the one about tracked shapes.
2. Pick a shape that one of your own FX animations moves.
3. If the shape moves in an animation outside FX, move that animation into the FX layer. See the message.
4. If a warning says the trigger reads only one card, move the conditions you need into that card. See the message.

See Drive effects from a blend shape.

Still stuck

See Report a bug.

A toggle is in the menu, but it does nothing

Likely cause

The toggle has no effects, or its targets are gone. A custom parameter name with no effects only drives the parameter, so something else has to read it.

Fix

1. Select the toggle and read its messages. A warning that it has no targets means nothing was built for it. See the message.
2. Press + Add effect and add an object, a blend shape, a material or a property.
3. If a row points at something that is gone, or at an object outside the avatar, open the row and fix or remove it. See a missing target and a target outside the avatar.
4. If the toggle drives a custom parameter on purpose, check that a merged animator, VRCFury or Modular Avatar reads it. A tool that makes its animation during the upload counts when it tells NDMF about its parameters. See the message.

See Toggle clothing and accessories.

Still stuck

See Report a bug.

A colour or glow does not change in VRChat

Likely cause

The material's shader locks the material at upload and fixed the property at its value. Poiyomi does this with every property that is not marked as animated. A material that was already locked before the property was marked keeps the old values too. Poiyomi leaves the materials locked after an upload, so a material locked at an earlier upload does not change in Play mode either.

A material swapped in outside AvatarDoc's own material rows, by your own animations, an AvatarDoc custom animation, a Modular Avatar Material Swap or VRCFury, is not checked by AvatarDoc, so no warning names it.

Fix

1. Select the toggle, radial or trigger and read its messages. A warning that a Poiyomi material does not mark the property as animated names the materials. Press Mark as animated under it. See the message.
2. A warning that a Poiyomi material is locked with the property fixed has no button. Select the material, press Unlock Shader at the top of its inspector, right-click the property and choose Animated (when locked). Then lock it again, or leave it: Poiyomi locks it at upload. See the message.
3. For a material swapped in outside AvatarDoc's material rows, and for another shader that locks its materials, mark the property as animated in the material's own inspector, then lock the material again.
4. When you add a property with the Add to AvatarDoc window, leave Mark as animated for Poiyomi's lock ticked: it marks the property as you add it.
5. Upload again and test in VRChat. Play mode shows the change only while the material is unlocked: a material locked at an earlier upload behaves there as it does in VRChat.

More about the marks: On a Poiyomi material.

Still stuck

See Report a bug.

Add to AvatarDoc is not in the right-click menu

Likely cause

• You right-clicked a material property. Unity offers that right click only to its Animation window, so it never shows the AvatarDoc item, with any shader.
• The blend shape was never set since the mesh was imported. Unity draws such a slider without the property the item needs.
• The item is there but greyed out: the mesh is not part of an avatar in the scene. The material's header item is also greyed out when no selected mesh under an avatar uses the material, such as a material selected in the Project window.

Fix

1. For a material property, select the mesh in the Hierarchy, press the three dots at the right end of the material's header under it, and choose Add to AvatarDoc.... It works with every shader, Poiyomi included. Pick the property in the window.
2. Or use the mesh's component menu: press the three dots at the right end of the Skinned Mesh Renderer or Mesh Renderer header, or right-click the header, and choose Add to AvatarDoc.... Pick the shape, or the material and the property, in the window.
3. For a blend shape, move its slider once, then right-click it again.
4. For a greyed out item, move the mesh under the avatar, the object that holds the VRChat Avatar Descriptor, and select the mesh, not the material in the Project window.

More about the window: Add to AvatarDoc window.

Still stuck

See Report a bug.

Two groups that used to be one now work apart

Likely cause

An exclusive group belongs to its AvatarDoc component. Your avatar's own component and a prefab's component each have a group of the same name, such as Outfits, and nothing links them, so they are two groups: turning on the prefab's outfit no longer turns off yours, and the two can be on at once. Up to version 0.6.0 they were one group.

Fix

1. Select a toggle of either group. The note in its panel names both components and the group. See the message.
2. To make them one group again, press Join them under the note. The toggles of the second component the note names join the group of the first, in one Undo step; the button's tooltip says which toggles move. When one of the two components is locked, the toggles of the other one move.
3. If the button is greyed out, both components are locked. Unlock one of them with Unlock, then press the button again.
4. To keep them apart on purpose, leave them: the avatar is still ready to upload. You may also give one of the groups another name.

The toggles that move take the other group's parameter, named after its component's prefix, so the choice they had saved starts from its default once.

See Groups of several components.

Still stuck

See Report a bug.

A toggle turns off a prefab's outfit, or a prefab's toggle turns off mine

Likely cause

The toggle is in the prefab's exclusive group, or a toggle of the prefab is in yours. Its Exclusive group was picked from the list as another component's group, and the note under the field, such as In the group of Mayo menu., names the component whose group it joined. A toggle of a group turns off every other toggle of that group.

Fix

1. Select the toggle and look at the note under Exclusive group.
2. To take it out of the other component's group, type a name in Exclusive group, which makes a group of the toggle's own component, or pick None from the list.
3. If the prefab's toggles turn yours off, select the prefab's component and do the same there. A locked component needs Unlock first.

See Groups of several components.

Still stuck

See Report a bug.

Some objects were not found when copying a menu

Likely cause

• The object has another name, or sits in another place, on the version you copy to: the base avatar renamed or moved it in its new release, or you did on one version only.
• The object is not on that version at all, such as an accessory you added to one version only.
• The object is there, but not with the component the entry needs, such as a mesh renderer or a second PhysBone.
• Several objects of one name sit side by side, and the two versions do not have the same number of them. The window then matches them by their order and says so in a note, and the match can be the wrong one.
• The object is marked Pick by hand when copying: the window always lists it for you to pick, even when the other version has an object at the same place.

Fix

1. In the Copy to another avatar window, under Objects it uses, pick the object to use for each row in Use instead. When the field already holds an object, it is a suggestion: the object at the same place, or the only object of that name. Check that it is the right one. The field takes only an object of the version you copy to.
2. A row that says Pick one before copying needs an object before Copy works: an empty path root would make the clips move other objects, and an empty Hold the rest mesh, grabbable object, contact anchor or PhysBone is an error that stops AvatarDoc building on that avatar.
3. Leave any other field empty to fix it later: the copy leaves that row of the entry empty, the build skips the row, and the entry's messages name it. See A target is missing.
4. For a note about objects of the same name, rename them on both versions so each name is used once, or check the copied rows after copying.
5. For an object you want to choose on every version, such as one a world drop holds, mark it on the version you copy from: right-click its row in the entry and choose Pick by hand when copying.

More about how the window finds objects: Copy to another avatar window.

Still stuck

See Report a bug.

VRChat or VRCFury warns about mixed Write Defaults

Likely cause

The layers of the avatar do not all use the same Write Defaults setting. AvatarDoc then builds its ordinary layers with Write Defaults on, and a warning names the layers on each side. Separately, AvatarDoc's pin layers are meant to have Write Defaults off, so VRCFury may report them as a mix.

Fix

1. To remove AvatarDoc's own warning, make the avatar's layers agree. The first line of Component settings shows the setting AvatarDoc uses.
2. When VRCFury offers to fix a mix and AvatarDoc has Pin rows or Fade triggers, choose Skip. If you press Auto-Fix, AvatarDoc turns its pin layers back off at the end of the upload.

See the message and Layers, Write Defaults and pinned layers.

Still stuck

See Report a bug.

The upload says a menu icon is too large

Likely cause

VRChat's upload check rejects an icon that is larger than 256 pixels on a side while its import size allows more, or that is not compressed.

Fix

1. Select the texture in the Project window.
2. In its import settings, set Max Size to 256, and set Compression to anything but None. Press Apply.
3. Or let AvatarDoc make the icon: Capture icon draws it at 256 by 256 pixels, which passes the check.

See the message and Icon capture.

Still stuck

See Report a bug.

A trigger has too many conditions

Likely cause

A trigger may have at most 4 groups of at most 4 conditions each, and at most 64 ways to turn off again. That last count is the product of the group sizes, so 4 groups of 4 conditions come to 256 and are refused. Limits explains the count with a table of what builds and what is refused. Beyond these caps, VRChat cannot build all the ways to turn the trigger off again, so the build stops with an error.

Fix

1. Select the trigger and count its groups under When.
2. Remove conditions you do not need, or merge groups.
3. If you need more, split the trigger into two triggers with the same effects.

See the message and Triggers.

Still stuck

See Report a bug.

A toolbar button I need is not there

Likely cause

The inspector is narrow. The toolbar shows as many add buttons as fit, and puts the others under + More. At 360 pixels wide, it shows + Toggle, + Radial and + Submenu. In Simple mode, the toolbar also leaves out the other adds on purpose.

Fix

1. Press + More and pick the add from its list. Each add has a one line description.
2. Or make the inspector wider, until every add shows as a button.
3. For + Override, + Preset and the other adds of Advanced mode, switch the mode row at the top of the inspector to Advanced.

See The inspector at a glance and Simple or Advanced?.

Still stuck

See Report a bug.

The tags on the tree rows, such as VRCFury or Existing, are missing

Likely cause

The tree is narrower than 360 pixels. A narrow tree leaves out the group, condition, source, asset and existing chips, and shows a platform chip only while the entry is not built for the current platform. The rows of other tools and of the avatar's own menu stay dimmed at every width.

Fix

1. Make the inspector wider, or use the AvatarDoc window from Tools > DocMe > AvatarDoc, which can be wider than the inspector.
2. The dimmed rows and the square icons still tell you that a row comes from another tool or from the avatar's own menu. The panel of the row names the tool.

See The inspector at a glance.

Still stuck

See Report a bug.