Troubleshooting

Symptom-first fixes for common integration issues. For onboarding, start with Quick start; for API lookup, use Server functions or Client functions.

• Client reads return nil
• Data never saves
• Client cannot write saved data
• Init fails or player has no profile
• Leaderboard empty or wrong
• OnChanged never fires
• Feedback

Client reads return nil

Symptom	Likely cause	What to do
Get / GetPath always nil	Server never called Init for that player	Call PlayerState.Init(player) on PlayerAdded — Quick start · Initialization
nil right after join	Replica not ready yet	Wait for IsReady() or use OnChanged after ready — Client status
nil for a key you set on server	Key is under ServerOnlyRoots or not in DefaultData	Check Data visibility · Server-only data
Wrong value or missing nested field	Typo in key/path, or reading before server write	Confirm path strings; verify server Set / SetPath — Paths

Data never saves

Symptom	Likely cause	What to do
Changes lost on rejoin	Writes only in memory; profile never saved	Saves run on leave, shutdown, and SaveData — ensure Init succeeded — Setup · Events
Specific keys never persist	Listed in RuntimeNonPersistentRoots (session data)	Session roots replicate but strip before save — Session data
Custom save logic skipped	BeforeSave handler error or early return	Review BeforeSave

Client cannot write saved data

This is expected. PlayerState does not ship client→server write remotes.

Symptom	Likely cause	What to do
Client script calls Set (or similar)	Client API is read-only	Add your own RemoteEvent; validate on server; call server APIs — Client writes via remotes · API overview

Init fails or player has no profile

Symptom	Likely cause	What to do
Init returns false	ProfileStore / config error, or player left during load	Check server output; review PlayerStateConfig and DefaultData — Configuration · Setup
Missing keys after join	Key not in DefaultData template	Add defaults in DefaultData; use Reconcile behaviour as documented in Setup
Require errors	Wrong module path after moving the model	Use canonical paths from Installation

Leaderboard empty or wrong

Symptom	Likely cause	What to do
No entries	Leaderboard disabled or stat path mismatch	Leaderboard configuration
Player rank missing	Stat not updated on server, or read before ready	Update via server APIs; check timing — Server leaderboard

OnChanged never fires

Symptom	Likely cause	What to do
No callbacks	Subscribed on wrong side (server vs client) or wrong path	Change listeners guide
Fires once then stops	Disconnected connection, or path does not match writes	Match exact key/path; use server OnChanged for server-driven tests
Never fires on join	Subscribed before IsReady without handling initial state	Wait for ready or read current value after subscribe — Client listeners

Feedback

Issue type	Where to report
Documentation errors, typos, broken links	playerstate_documentation on GitHub (use Suggest an edit on any page)
Module behaviour in your game	Creator Store asset — there is no separate public module repo linked from these docs