Troubleshooting and FAQ

Scanning

The first Entire Project scan is slow. Expected. RefSafe builds its asset dependency map from scratch on the first run, and that cost is proportional to project size. Later scans reuse the cache. For a routine loop, use ChangedOnly scope.

A scan found nothing, but I know something is broken. Check the scope first — OpenScenes won’t see a broken prefab that isn’t in a loaded scene. Then check Settings: the relevant rule may be disabled, and Huge Position and Prefab Variant Override ship off by default.

Issues I already fixed still show up. Results reflect the last completed scan. Re-scan. If they persist after a scan, the fix may have reported failure — check the Unity console.

Can I scan while the editor is compiling? No. Wait for compilation to finish. Scanning depends on loaded assemblies to resolve component types.

Unused assets

An asset is flagged as unused but is definitely used. RefSafe finds static references — serialized links between assets. It cannot see assets loaded by string path through Resources.Load, by address through Addressables at runtime, by name from code, or from bundles built outside the normal dependency graph.

Add path patterns for these to the Cleaner’s protected list. Assets/Resources/** is the usual first entry.

Why is a sprite atlas flagged? Atlases are frequently reference-free by design. They’re covered by the built-in protection defaults, so they’ll be excluded from deletion even when listed.

Fixing

The Fix button isn’t there. Not every issue has an unambiguous automatic fix. RefSafe deliberately doesn’t guess where guessing could destroy work — InvalidLayer, for instance, can’t know which layer you meant.

Fix All did more than I expected. Fix All applies every available fix in the current result set, respecting active filters. Filter first to scope it. Undo reverts a batch as a single operation.

Can I undo a fix? Yes — every fix registers a Unity Undo group, batch fixes included. Custom fixers need to use Undo.RecordObject / Undo.DestroyObjectImmediate to participate.

Cleaner

I deleted something I shouldn’t have. RefSafe exports a .unitypackage backup before every batch delete. Use Restore in the Cleaner toolbar to re-import the most recent one.

Duplicate detection missed identical files. Detection buckets by file size, then confirms with MD5. Files that are visually identical but differ by a byte — different compression settings, different import metadata — are genuinely different files and won’t match.

Trends

My health score dropped but I didn’t break anything. Common causes: a rule you enabled surfaced an existing backlog at once, a snooze expired, or you widened the scan scope. Compare the two scans to see exactly what changed.

Scan history is empty on a teammate’s machine. History lives in Library/RefSafePro/History.json, which isn’t committed. It’s per-machine by design.

CI and CLI

The CI job exits 2. Exit code 2 is a scan error, not a validation failure — check the Unity log. Usual causes are licensing failures in batchmode, a project that didn’t compile, or a bad --projectPath.

--format isn’t recognized. The value must match a registered exporter id exactly, in lowercase. Built-ins are csv, json, html, txt, markdown, github, gitlab. For a custom exporter, the id is the first argument of its [ReportExporter] attribute.

Should I use ChangedOnly in CI? Generally no. It depends on RefSafe’s incremental tracker, which is per-machine state. On an ephemeral runner with a clean checkout there’s no prior scan to diff against, so it effectively runs a full scan. It’s a local-loop optimization.

Settings and version control

Which files should I commit? Commit Assets/RefSafe/Pro/Editor/Settings/Settings.asset — rule configuration is a team decision. Don’t commit Library/RefSafePro/; it holds per-user state and cached scan data, and Library/ is git-ignored by Unity convention anyway.

A teammate’s ignored issues are hidden from me. They aren’t. Ignores and snoozes are per-user by design, so they don’t create merge noise or silently hide problems across a team.

Extending

My custom rule doesn’t appear in Settings. It needs the [ValidationRule] attribute, a public class, a parameterless constructor, and an assembly referencing RefSafe.Pro.Editor. Then trigger a domain reload.

I’m getting RuleFault issues. A custom rule, fixer, or exporter threw. RefSafe caught it so the scan could finish. The stack trace is in the Unity console.

Still stuck?

Email [email protected] with your Unity version, RefSafe Pro version, and the console output. See support.