Troubleshooting
Sync troubleshooting
Fix Team OS file sync problems.
| Symptom | Likely cause | Fix |
|---|---|---|
| Manifest is empty for a Member | No active client grant. | Check npm run team -- clients and client grants. |
| Manifest is empty for a Full access user | Wrong Team, inactive authority, or no syncable client files. | Confirm the selected Team and effective access, then inspect exclusions. |
| Pull returns no files | Client has no syncable text files. | Check excluded paths and file size. |
| Push is denied | User has read, not write. | Grant write access for that client. |
| Push says no base version | Existing file was not pulled first. | Run sync pull, merge changes, then push. |
| Push gets a conflict | Remote file changed after pull. | Pull fresh, merge manually, then push. |
| Command Centre asks to review files | Local and server files both changed, or one side deleted a file. | Review the diff before confirming. |
The terminal sync push command skips secret-named files, generated folders,
transcripts, non-text files, and files larger than 1 MB. Command Centre client
sync is broader: it can include regular text or binary files up to 25 MB.
Secret-named files are visible only with write access and are marked for
extra care.
Use the Team OS Secrets section when a value should be managed as a Team secret. Review the file list before confirming a client sync.
Stale Command Centre state
If Command Centre shows old Team OS data:
- Refresh the current Team section.
- Confirm the terminal and UI use the same
AGENTIC_OS_TEAM_CONFIG_DIR. - Confirm the correct Team is selected.
- Run
npm run team -- whoami. - Sign out with
npm run team -- logout. - Start Command Centre again and sign in.
If the backend is unavailable, hosted mode should not silently show every local client folder as if it came from Team OS.
Next: API and database health