⚙️ Setup & Reference — Series 4 of 4
This page covers the most common issues encountered when setting up the NP 3D Viewer and Variation Wizard, along with their causes and fixes.
NP 3D Viewer Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Viewer shows blank / white canvas | Model URL is inaccessible or returns 403/404 | Verify the URL is publicly reachable. Open it directly in a browser tab — it should download the .glb file. Check for CORS headers if hosted on a CDN. |
| Viewer doesn’t appear on product page | 3D Viewer Enabled toggle is off, or NexPoint 3D Configurator metabox has no model assigned | On the product edit page, open the NexPoint 3D Configurator metabox → enable 3D Viewer Enabled → confirm a model URL is set either in the metabox or in NP 3D Viewer → Model Assignments. |
| Model appears too large or tiny | Default Model Scale is wrong for the file’s unit system | Adjust Model Scale in the NexPoint 3D Configurator metabox (start with 0.01 for cm-exported models, 1.0 for metre-scale). Or set a global default in NP 3D Viewer → Settings. |
| Background color not showing | Hex value missing the # prefix, or an environment preset is overriding it | Ensure Background Color is a valid hex (e.g. #ffffff). Set Environment Preset to None if you want a pure flat background color. |
| Auto-rotate not working | Auto-Rotate checkbox is unchecked | Enable Auto-Rotate in the NexPoint 3D Configurator metabox for the product. |
Material Slot Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Color slide doesn’t update the 3D model | Slot name in the wizard doesn’t match the material name in the GLB file | Use the Scan button in NP 3D Viewer → Model Assignments → Material Slots to auto-detect slot names. Copy the name exactly — names are case-sensitive. |
| Only one mesh updates, not all linked meshes | Multi-slot comma list is incomplete | In the Color Slide’s Material Slots field, enter all slot names separated by commas: Logo1,Logo1_All. |
| Slots table is empty after scanning | Model URL returned an error when scanned, or GLB has no named materials | Confirm the model URL is accessible, then re-scan. If the GLB uses default material names like Material.001, rename them in your 3D software and re-export. |
Variation Wizard Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Wizard doesn’t appear on product page | Product Mode is set to Simple 3D instead of Full Wizard | In the NexPoint 3D Configurator metabox, set Product Mode to Full Wizard. |
| Wizard slides are empty / show no options | Attribute not linked to the product, or no terms added | Go to the product’s Attributes tab → confirm the attribute is added and terms are selected. See Setting Up WooCommerce Attributes. |
| Color swatches show as grey circles | Terms are missing hex color values | Edit each attribute term under WooCommerce → Attributes → [Attribute] → Configure terms and add a hex color value. |
| Add to Cart button missing | Summary slide not added as last wizard slide | The Summary slide must always be the final slide — it contains the Add to Cart button. Add a Summary slide at the end of the wizard. |
| Wizard shows on simple products | Product Mode set to Full Wizard on a non-configured product | Set Product Mode to Simple 3D for products that should use the standard WooCommerce cart. |
Plugin Activation Issues
| Symptom | Likely Cause | Fix |
|---|---|---|
| Dependency error on activation | NP Core not activated first | Deactivate the erroring plugin, activate NP Core, then re-activate the other plugin. |
| “WooCommerce required” notice | WooCommerce is inactive | Install and activate WooCommerce, then re-activate the NP plugin. |
| Metabox not showing on product edit page | NP Core or NP 3D Viewer not active | Confirm both NP Core and NP 3D Viewer are active under Plugins → Installed Plugins. |
ℹ️ Still stuck? Check the browser’s JavaScript console (F12 → Console tab) for errors starting with
NP: or np-viewer — these often pinpoint the exact cause. You can also check the WordPress debug log at wp-content/debug.log if WP_DEBUG_LOG is enabled.Ready to add 3D to your WooCommerce store?
Get the NP Matrix plugin suite or try it instantly — no install required.
The playground runs entirely in your browser — no account needed.