This page covers common issues and their solutions. If you encounter an error not covered here, check the Unity Console for detailed error messages.

Missing Assembly References

Symptom: Errors like "The type or namespace name 'Photon' could not be found"

Cause: The required networking package is not installed

Solution: Install the networking SDK you're using (Photon PUN, Mirror, etc.) before importing Universal Friend List

Duplicate Script Definitions

Symptom: Errors about duplicate class definitions

Cause: The package was imported multiple times or scripts exist in multiple folders

Solution: Check for duplicate folders under Assets and remove any duplicate imports

FriendManager Instance Not Found

Symptom: "FriendManager instance not found" error

Solutions:

• Ensure FriendManagerInitializer is in your starting scene
• Check that InitializeOnStart is enabled OR Initialize() is called manually
• Verify the FriendManagerSettings asset exists and is assigned

User ID Not Set

Symptom: Friend operations fail with "User ID not set" error

Solutions:

• For Native Photon: Ensure Photon is connected before using friends
• For Custom Backend: Set UserId on FriendManagerInitializer or call Initialize(userId)

Cannot Connect to Custom Server

Symptom: HTTP/WebSocket connection failures

Solutions:

• Verify server is running (npm start or php -S localhost:3000)
• Check ServerUrl matches your server address (no trailing slash)
• For WebSocket: ensure using ws:// or wss:// (not http://)
• Check firewall settings allow the connection
• Verify CORS settings in server config

WebSocket Disconnects Frequently

Symptom: WebSocket connection drops

Solutions:

• Increase heartbeat interval on server
• Check for network instability
• Ensure no firewall timeout settings are closing idle connections
• Enable WebSocket keep-alive on client side

Friend Requests Not Being Sent

Solutions:

• Check the user ID is valid and exists
• Verify you haven't exceeded friend limit (MaxFriends setting)
• Ensure the target user is not already your friend
• Check if the target user has blocked you

Friend List Always Empty

Solutions:

• For Native: Ensure you're connected to the same region as friends
• For Custom Server: Verify authentication is working correctly
• Check if friends list persistence is loading correctly
• Try calling RefreshFriendList() manually

Photon App ID Not Set

Symptom: Cannot connect to Photon

Solution: In Unity, go to Window → Photon Unity Networking → Highlight your project, or locate the PhotonServerSettings asset and enter your App ID from the Photon Dashboard.

Native Friends Not Working

Solutions:

• Ensure UseNativeImplementation is set to true in settings
• Check BackendType matches PhotonPUN or PhotonFusion
• Verify Photon is properly connected before friend operations
• Both users must be connected to the same Photon region

To help diagnose issues, enable verbose logging:

// In your code
ElderWorldStudioLogger.SetLogLevel(LogLevel.Verbose);

// Or in FriendManagerSettings
// Enable "Enable Debug Logging" toggle

Logs will show all API calls, responses, and network operations.

If issues persist:

• Check the Unity Console for detailed error messages
• Enable debug logging and review the output
• Check the Asset Store support page
• Include the full error message and steps to reproduce when contacting support