Troubleshooting

Common issues and solutions for Asset Atlas.

Installation Issues

Plugin Not Appearing in Menu

Symptoms: No "Asset Atlas" in Window menu after installation.

Solutions:

1. Verify the plugin is enabled:
2. Edit > Plugins > Search "Asset Atlas"
3. Ensure checkbox is checked

4. Restart editor

5. Check engine version:

6. Asset Atlas requires UE 5.4+

7. Earlier versions are not supported

8. Verify installation:

9. Check Fab Library shows "Installed"
10. Try reinstalling from Fab

Compilation Errors

Symptoms: Build errors when compiling with Asset Atlas.

Solutions:

1. Ensure Visual Studio/Xcode is properly configured
2. Verify you have the correct engine version
3. Try regenerating project files:
4. Right-click .uproject > Generate Project Files

Scanning Issues

Scan Takes Too Long

Symptoms: Scanning hangs or takes many minutes.

Solutions:

1. Exclude unnecessary folders:
2. Project Settings > Asset Atlas > Excluded Folders

3. Add /Game/Developers, test folders, etc.

4. Disable external packages:

5. Uncheck "Include External Packages"

6. This skips plugin/engine assets

7. Check project size:

8. Very large projects (10,000+ assets) naturally take longer
9. Consider scanning specific folders

Scan Shows 0 Assets

Symptoms: Scan completes but shows no assets.

Solutions:

1. Verify your project has content in /Game/
2. Check excluded folders aren't too broad
3. Ensure you're in a valid UE project
4. Try rescanning (triple-click refresh for force)

Scan Crashes Editor

Symptoms: Editor crashes during or after scan.

Solutions:

1. Update to latest version from Fab
2. Check for corrupted assets:
3. Look for assets that crash when opening
4. Remove or fix them
5. Reduce scope:
6. Exclude problematic folders
7. Scan smaller portions first
8. Report issue with crash log to support

Graph Display Issues

Graph Is Empty

Symptoms: Graph shows no nodes or clusters.

Solutions:

1. Ensure scan completed successfully
2. Clear any active filters (click Reset)
3. Check search box is empty
4. Zoom out (scroll wheel)

Nodes Overlap

Symptoms: Asset nodes or clusters overlap each other.

Solutions:

1. Increase spacing: Click the + button
2. Collapse clusters: Click expanded clusters to collapse
3. Use filters: Reduce visible nodes
4. Reset view: Click Reset button

Graph Performance Is Poor

Symptoms: Lag when panning, zooming, or expanding.

Solutions:

1. Reduce Max Visible Nodes:
2. Project Settings > Asset Atlas

3. Lower to 100-200

4. Keep clusters collapsed:

5. Only expand when needed

6. Use filters:

7. Filter by type or folder to reduce nodes

8. Disable overlays:

9. Turn off Asset Optics integration if not needed

Grading Issues

Grade Seems Wrong

Symptoms: Grade doesn't match expectations (e.g., clean project gets C).

Solutions:

1. Check preset:
2. Different presets have different thresholds

3. Try "Lenient" or "SampleProject" for sample content

4. Review the tooltip:

5. Hover over ⓘ on Project Health card

6. See exact scoring breakdown

7. Check ignored items:

8. Ignored orphans/circulars are excluded

9. Ignore intentionally unused assets

10. Adjust custom rules:

11. Create custom JSON preset
12. Tune thresholds for your project

Orphan Count Is High

Symptoms: Many orphans reported but assets seem used.

Causes:

• Level streaming: Maps load assets not shown as references
• Dynamic loading: LoadObject calls not detected
• Soft references: May not be counted as dependencies
• Code references: C++ references not always tracked

Solutions:

1. Use Ignore for false positives
2. Review if assets are truly unused
3. Check Reference Viewer for details

Circular Count Is High

Symptoms: Many circulars reported but seem like false positives.

Solutions:

1. Increase minimum chain length:

2. Use custom preset with minChainLength: 4

3. Use filters:

4. Enable "Ignore Engine Assets"

5. Enable "Ignore Self References"

6. Ignore known patterns:

7. Click Ignore on acceptable chains

Integration Issues

Asset Optics Not Working

Symptoms: No Asset Optics overlays or menu items.

Solutions:

1. Verify Asset Optics is installed:
2. Check Edit > Plugins

3. Asset Optics must be enabled

4. Enable integration:

5. Project Settings > Asset Atlas

6. Check "Enable Asset Optics Integration"

7. Set Project ID:

8. Get ID from Asset Optics settings

9. Enter in Asset Atlas settings

10. Check network:

11. Verify internet connection
12. Check backend URL if self-hosted

Context Menu Items Missing

Symptoms: Right-click menu doesn't show expected options.

Solutions:

1. Ensure you right-clicked an asset node (not cluster)
2. Verify Asset Optics integration is enabled
3. Check Asset Optics plugin is loaded

General Issues

Settings Not Saving

Symptoms: Changes to settings revert after restart.

Solutions:

1. Ensure you have write access to Config folder
2. Check project isn't read-only
3. Try "Save All" after changing settings

Onboarding Won't Show

Symptoms: Can't restart the onboarding wizard.

Solutions:

1. Click ? button in header
2. Select "Start Onboarding Tutorial"
3. If still missing, check project state file

Export Not Working

Symptoms: Export Report button does nothing.

Solutions:

1. Ensure you have scan results (scan first)
2. Check you have write access to the export location
3. Try exporting to a different location

Getting Help

If issues persist:

1. Email: assetoptics@brahmaforge.com
2. Include:
3. UE version
4. Asset Atlas version
5. Steps to reproduce
6. Crash logs (if applicable)

---

Installation Configuration