Sync Troubleshooting
How to diagnose and resolve sync errors in Codex
Codex syncs your project files to a remote server so your team can collaborate. When sync fails, your changes may not reach your teammates, or your project may show outdated content. This page covers the most common sync errors and how to resolve them.
Before Troubleshooting
Make sure you are on the latest version of Codex before attempting any of the steps below. Many sync issues are fixed in newer releases.
- Go to Help > About Codex and note your version.
- Compare to the latest release.
- Update if needed, then check whether the sync issue persists.
"Sync failed" or "Failed dircache magic file number" error
Do not delete project files manually. Deleting local project files to fix a sync error can cause data loss. Always contact support first.
This error occurs when a project's local files become corrupted during a sync operation. It is a known issue that cannot be resolved by the user from within the product.
What to do:
- Note the exact error message text.
- Note your project name and Codex version (Help > About Codex).
- Go to the Troubleshooting guide, select "Sync or offline behavior is strange", and complete the support form at the end. Include SYNC ERROR in the description field.
- Paste the generated template into Discord.
The team will resolve this from the server side. Do not attempt to re-import or recreate the project until you hear back from support.
Changes not appearing for teammates
If you have made changes but your teammates cannot see them:
- Check your internet connection — sync requires a stable connection.
- In your project, look for the Sync button or indicator. Click it manually to trigger a sync.
- Ask your teammates to also click Sync on their devices.
- If sync is still not working after 10 minutes, check the Console in Developer Tools (Help > Toggle Developer Tools) for red error messages. Copy any errors you find.
- If the problem persists, go to the Troubleshooting guide and complete the support form. Include the console errors in the error text field, then paste the generated template into Discord.
Project shows outdated content after a team member made changes
- Close and reopen the project to trigger a fresh sync.
- If the content is still outdated: click the Sync button manually.
- Ask the team member who made the changes to confirm their changes saved and synced on their side.
- If you are consistently seeing outdated content, go to the Troubleshooting guide and complete the support form. Describe what content you expect vs what you see, then paste the generated template into Discord.
The yellow sync indicator will not go away
A yellow unsynced indicator means your project has local changes that have not yet synced to the server.
- Check your internet connection.
- Click the Sync button to attempt a manual sync.
- If the indicator persists with a stable connection: check Developer Tools console (Help > Toggle Developer Tools) for errors. Copy any red error messages.
- Go to the Troubleshooting guide and complete the support form. Include the console errors in the error text field, then paste the generated template into Discord.
Still stuck?
- Review Reporting Bugs to collect console logs — this significantly speeds up diagnosis.
- Go to the Troubleshooting guide and complete the full support form. It will collect your version, OS, reproduction steps, and error details into a single template.
- Paste the generated template into Discord. This gives the support team everything they need without back-and-forth.