anthropic-skills/unity3d-enhanced/reference/common-errors.md

Common Unity Errors Catalog

Overview

This document catalogs common Unity errors with their causes, solutions, and prevention strategies. Search by error message or keyword to quickly find solutions.

---

GUID and Meta File Errors

Could not extract GUID

Error:

Could not extract GUID in text file Assets/Prefabs/MyPrefab.prefab at line 97.

Cause: Invalid GUID format (non-hexadecimal characters)

Solution:

1. Find correct GUID: grep "^guid:" Assets/Scripts/MyScript.cs.meta
2. Replace invalid GUID in prefab file
3. Ensure GUID is 32 hexadecimal characters (0-9, a-f)

Prevention: Never manually create GUIDs; always copy from .meta files

→ See reference/guid-system.md for details

Broken PPtr

Error:

Broken PPtr [guid 1234...] in file Assets/Scenes/MyScene.unity

Cause: Reference to deleted asset (orphaned .meta file)

Solution:

# Find and remove orphaned meta files
for meta in Assets/**/*.meta; do
    [ -f "${meta%.meta}" ] || git rm "$meta"
done

Prevention: Delete files via Unity Editor or delete both .cs and .meta together

→ See reference/guid-system.md for details

---

Input System Errors

InvalidOperationException: Input System

Error:

InvalidOperationException: You are trying to read Input using the UnityEngine.Input class,
but you have switched active Input handling to Input System package in Player Settings.

Cause: Using legacy Input API when project configured for new Input System only

Solution: Change activeInputHandler to 2 (Both) in ProjectSettings/ProjectSettings.asset:

activeInputHandler: 2

Or via Editor: Edit → Project Settings → Player → Active Input Handling → Both

Prevention: Check Input System configuration before writing input code

→ See reference/input-systems.md for details

Keyboard.current is null

Error: NullReferenceException when accessing Keyboard.current

Cause: Keyboard device not connected or not initialized

Solution:

// Always null-check devices
if (Keyboard.current != null && Keyboard.current.spaceKey.wasPressedThisFrame)
{
    Jump();
}

Prevention: Always null-check device references in new Input System

→ See reference/input-systems.md for details

---

URP Errors

Camera data is null

Error:

Camera data is null. Please ensure the render pipeline is correctly initialized
and the camera has a UniversalAdditionalCameraData component.

Cause: Camera's m_RendererIndex set to -1 (invalid) in URP scene

Solution: Change in .unity scene file:

m_RendererIndex: 0  # Changed from -1

Prevention: Always create cameras via Unity Editor when using URP

→ See reference/urp-setup.md for details

Pink Materials (Shader Error)

Symptom: Materials appear bright pink/magenta

Cause: Shader not compatible with active render pipeline

Solution:

1. Automatic: Edit → Render Pipeline → URP → Upgrade Project Materials
2. Manual: Change shader to URP equivalent
   • Standard → Universal Render Pipeline/Lit
   • Unlit → Universal Render Pipeline/Unlit

Prevention: Use URP-compatible shaders from the start

→ See reference/urp-setup.md for details

---

Physics Errors

Objects fall through floor

Symptom: Rigidbody objects pass through colliders

Causes:

• Fast-moving objects (tunneling)
• Collider too thin
• Layer collision matrix disabled
• Missing Rigidbody

Solutions:

1. Use Continuous Collision Detection:

   rb.collisionDetectionMode = CollisionDetectionMode.Continuous;
   

2. Increase collider thickness
3. Check layer collision matrix (Edit → Project Settings → Physics)
4. Use triggers for fast objects

Prevention: Use appropriate collision detection mode for object speed

→ See reference/physics-system.md for details

Triggers not detecting

Symptom: OnTriggerEnter not called

Causes:

• No Rigidbody on either object
• Layer collision matrix disabled
• IsTrigger not set to true
• Callback method misspelled

Solutions:

1. Add Rigidbody to at least one object
2. Verify layer collision matrix enabled
3. Check collider has IsTrigger = true
4. Verify method signature exact: void OnTriggerEnter(Collider other)

Prevention: Ensure at least one Rigidbody present for trigger detection

→ See reference/physics-system.md for details

---

NullReferenceException Errors

Unassigned SerializeField

Error:

NullReferenceException: Object reference not set to an instance of an object
ComponentName.MethodName () (at Assets/Scripts/ComponentName.cs:42)

Cause: [SerializeField] field not assigned in Inspector

Example:

[SerializeField] private Transform targetTransform;  // Not assigned!

void Start()
{
    Vector3 pos = targetTransform.position;  // ← Throws here
}

Solutions:

1. Assign field in Inspector
2. Add null check:

   if (targetTransform == null)
   {
       Debug.LogError("Target not assigned!");
       return;
   }
   

3. Use OnValidate:

   void OnValidate()
   {
       if (targetTransform == null)
           Debug.LogWarning($"{name}: Target not assigned!");
   }
   

Prevention: Always assign SerializeField references or add null checks

GetComponent returns null

Error: NullReferenceException after GetComponent

Cause: Component doesn't exist on GameObject

Solution:

// ❌ Unsafe
Rigidbody rb = GetComponent<Rigidbody>();
rb.velocity = Vector3.zero;  // Crash if no Rigidbody!

// ✓ Safe
if (TryGetComponent<Rigidbody>(out var rb))
{
    rb.linearVelocity = Vector3.zero;
}
else
{
    Debug.LogError("Rigidbody not found!");
}

Prevention: Use TryGetComponent or null-check GetComponent results

---

Resources Loading Errors

Resources.Load returns null

Error: Resources.Load returns null, file exists but not loading

Cause: File not in Assets/Resources/ folder

Solution:

1. Create Assets/Resources/ folder structure
2. Move files into Resources folder
3. Load without extension or path prefix:

   // File at: Assets/Resources/Data/config.json
   TextAsset data = Resources.Load<TextAsset>("Data/config");
   

Prevention: Understand Resources.Load() only works with Resources folders

---

Compiler Warnings (Treat as Errors)

CS0414: Field assigned but never used

Warning:

Assets/Scripts/MyScript.cs(19,25): warning CS0414:
The field 'MyScript.myField' is assigned but its value is never used

Cause: SerializeField declared but never accessed in code

Solution: Actually use the field in your logic:

[SerializeField] private float speed = 5f;

void Update()
{
    // Use the field!
    transform.position += transform.forward * speed * Time.deltaTime;
}

Prevention: Use fields immediately after declaration; test Inspector changes

CS0649: Field never assigned

Warning:

warning CS0649: Field 'MyClass.myField' is never assigned to,
and will always have its default value null

Cause: Private field without [SerializeField] that's never assigned in code

Solution:

1. Add [SerializeField] if assigning in Inspector
2. Or assign in code
3. Or remove if unused

---

Build Errors

Scripts have compiler errors

Error: Cannot build due to compiler errors

Cause: Syntax errors, missing namespaces, or API mismatches

Solution:

1. Open Console (Window → General → Console)
2. Fix all red errors
3. Clear all yellow warnings (treat them seriously!)
4. Verify script compiles: Assets → Reimport All

Missing assembly references

Error:

error CS0246: The type or namespace name 'InputSystem' could not be found

Cause: Missing package or assembly reference

Solution:

1. Install required package via Package Manager
2. Add assembly reference in .asmdef (if using assembly definitions)
3. Check using statements

---

API Deprecation Warnings

Rigidbody.velocity is obsolete

Warning:

'Rigidbody.velocity' is obsolete: 'Use linearVelocity instead.'

Cause: Using deprecated API in Unity 2023.1+

Solution:

// Old (pre-2023.1)
rb.velocity = Vector3.forward;

// New (2023.1+)
rb.linearVelocity = Vector3.forward;

Prevention: Keep up with Unity API changes when upgrading versions

→ See reference/physics-system.md for details

---

Performance Warnings

Too many vertices in mesh

Warning: Mesh has excessive vertex count

Solution:

1. Reduce polygon count in 3D software
2. Use LOD (Level of Detail) system
3. Enable mesh compression

Too many draw calls

Symptom: Low framerate, many draw calls in Profiler

Solution:

1. Enable Static Batching (mark objects static)
2. Use GPU Instancing on materials
3. Combine meshes
4. Use texture atlases

---

Platform-Specific Errors

Android Build Failed

Common causes:

• Missing Android SDK/NDK
• Incorrect API level
• Keystore issues
• Permissions not set

Solution:

1. Edit → Preferences → External Tools → Set Android SDK/NDK
2. Player Settings → Android → Set minimum API level
3. Configure keystore
4. Add required permissions in manifest

iOS Build Failed

Common causes:

• Xcode not installed
• Invalid bundle identifier
• Missing capabilities
• Code signing issues

Solution:

1. Install latest Xcode
2. Set valid bundle identifier
3. Configure capabilities in Xcode project
4. Set up code signing

---

Debugging Strategies

General Approach

1. Read the full error message - often contains the solution
2. Note the line number - error location is critical
3. Check recent changes - what changed before the error?
4. Google the exact error - likely someone else solved it
5. Check Unity Forums - official community support
6. Profile if performance - use Unity Profiler

Console Tools

// Basic logging
Debug.Log("Value: " + value);

// Warnings and errors
Debug.LogWarning("This might be a problem");
Debug.LogError("This is definitely wrong");

// Conditional logging
Debug.Assert(value != null, "Value should not be null!");

// Context logging (clickable in Console)
Debug.Log("Object info", gameObject);

Break on Error

Edit → Preferences → General → Error Pause

• Enable to pause Editor when error occurs
• Helpful for debugging runtime errors

---

Quick Reference: Error Keywords

Error Keyword	Common Cause	Quick Fix
GUID	Invalid or missing GUID	Copy from .meta file
Input System	API mismatch	Set activeInputHandler: 2
Camera data is null	URP renderer index	Set m_RendererIndex: 0
NullReferenceException	Unassigned field	Assign in Inspector or null-check
Resources.Load	Wrong folder	Move to Resources/ folder
velocity obsolete	Old API (2023.1+)	Use linearVelocity
CS0414	Unused field	Actually use the field
Pink material	Wrong shader	Use URP shaders
Trigger not working	Missing Rigidbody	Add Rigidbody component
Broken PPtr	Orphaned meta file	Remove orphaned .meta

---

Additional Resources

• Unity Documentation
• Unity Forums
• Unity Answers
• Stack Overflow - Unity Tag
• Unity Issue Tracker