mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
Ethan Palm
bdd9b51155
Adds editor/troubleshooting.mdx covering sync failures, publish errors, branch confusion, conflict resolution, and blank editor states. Adds cli/troubleshooting.mdx covering mint dev startup, port conflicts, missing pages, broken links, OpenAPI issues, and deploy-only failures. Both pages are added to docs.json navigation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
93 lines
7.3 KiB
Plaintext
93 lines
7.3 KiB
Plaintext
---
|
|
title: "Troubleshooting the editor"
|
|
description: "Fix common web editor problems including sync failures, publishing errors, branch conflicts, and connection issues."
|
|
keywords: ["editor troubleshooting", "sync issue", "publish failed", "branch conflict", "editor not loading"]
|
|
---
|
|
|
|
<AccordionGroup>
|
|
|
|
<Accordion title="My changes aren't appearing on the live site after publishing">
|
|
Publishing commits your changes to Git and triggers a deployment. If the live site hasn't updated:
|
|
|
|
1. Check the deployment status on the [Overview](https://app.mintlify.com/) page of your dashboard. Deployments typically take 30 seconds to a few minutes.
|
|
2. Hard-refresh your browser (`Cmd+Shift+R` on Mac, `Ctrl+Shift+R` on Windows) to clear the cache.
|
|
3. If the deployment shows as failed, go to your dashboard, check the error details, and manually trigger a new deployment.
|
|
4. Confirm you published to the correct branch. If you're on a feature branch, your changes go to a preview URL, not the live site. Merge the branch to deploy to production.
|
|
</Accordion>
|
|
|
|
<Accordion title="The publish button is disabled or my changes aren't saving">
|
|
The publish button is disabled when there are no pending changes, or when another publish is already in progress on the same branch.
|
|
|
|
- **No pending changes**: The editor only tracks certain change types — content edits, new or deleted pages, navigation changes, media uploads, and configuration updates. If your change isn't tracked, the publish button stays disabled.
|
|
- **Another publish in progress**: Only one publish can run at a time per branch. Wait for the current publish to complete before trying again.
|
|
- **Branch protection requires a pull request**: If your deployment branch requires pull requests, the editor shows "Create branch" instead of "Publish". Move your changes to a feature branch, then open a pull request.
|
|
</Accordion>
|
|
|
|
<Accordion title="My edits disappeared or were overwritten">
|
|
The editor autosaves continuously and persists changes across devices and network interruptions. If changes seem to have disappeared:
|
|
|
|
1. **Check your branch**: You may have switched branches. Click the branch name in the toolbar to verify you're on the correct branch.
|
|
2. **Check for a merge**: If a teammate merged a pull request that affected the same files, the merged version is now live and your branch may need to be updated.
|
|
3. **Check for conflicts**: If a remote push conflicts with your edits, the editor highlights the conflict for resolution. Look for a conflict warning in the toolbar or on the affected page.
|
|
|
|
Changes that were autosaved but not yet published remain on the branch they were saved to. Switch to that branch to recover them.
|
|
</Accordion>
|
|
|
|
<Accordion title="The editor shows a sync error or is out of sync with Git">
|
|
The editor syncs with your Git repository continuously. A sync error usually means the editor couldn't reach GitHub or GitLab, or there's a conflict between your local changes and a remote push.
|
|
|
|
1. **Reload the editor**: Refresh the page. The editor re-syncs on load.
|
|
2. **Check your Git provider status**: Visit [githubstatus.com](https://www.githubstatus.com/) or [status.gitlab.com](https://status.gitlab.com/) to see if there's an ongoing incident.
|
|
3. **Resolve conflicts**: If the sync error is due to a conflict, the editor shows which files are affected. Open each file and choose which version to keep.
|
|
4. **Check the GitHub App**: If the editor can't push commits, the Mintlify GitHub App may have lost access. Go to [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) in your dashboard and verify the app is installed and the repository is connected.
|
|
|
|
If the editor consistently fails to sync after reloading, try opening the editor in a private browser window to rule out a browser extension conflict.
|
|
</Accordion>
|
|
|
|
<Accordion title="I see a conflict warning when switching branches or publishing">
|
|
Conflicts occur when your branch and the target branch have incompatible changes to the same files.
|
|
|
|
- **When publishing**: The editor displays a conflict warning. Follow the prompts to choose which version of each conflicting section to keep.
|
|
- **When switching branches**: You're asked whether to bring your pending changes to the new branch or leave them behind. Bringing changes to a branch with conflicting content triggers a conflict resolution flow.
|
|
|
|
To avoid conflicts, pull the latest changes before starting work on a page that teammates are actively editing.
|
|
</Accordion>
|
|
|
|
<Accordion title="The editor isn't loading or shows a blank page">
|
|
1. **Clear your browser cache**: A stale cache can prevent the editor from loading correctly. Hard-refresh with `Cmd+Shift+R` (Mac) or `Ctrl+Shift+R` (Windows).
|
|
2. **Try a different browser**: Test in Chrome or Firefox to rule out a browser-specific issue.
|
|
3. **Disable browser extensions**: Ad blockers and content-security-policy extensions can interfere with the editor. Try loading in a private window.
|
|
4. **Check your network**: The editor requires access to `app.mintlify.com` and your Git provider. If you're on a VPN or corporate network, confirm these are reachable.
|
|
5. **Check status**: Visit [status.mintlify.com](https://status.mintlify.com) to see if there's an active incident.
|
|
</Accordion>
|
|
|
|
<Accordion title="My changes were published but the deployment failed">
|
|
Publishing commits your changes to Git, and Mintlify automatically builds and deploys from there. If the commit succeeded but the deployment failed:
|
|
|
|
1. Go to the [Overview](https://app.mintlify.com/) page of your dashboard to see the build error details.
|
|
2. Common build failures include broken internal links, invalid `docs.json` configuration, or missing files referenced in navigation. Fix the issue in the editor and publish again.
|
|
3. If the build error isn't clear, run `mint dev` locally to reproduce it — the CLI shows detailed error output. See [Install the CLI](/cli/install) to get started.
|
|
4. After fixing the issue, you can also manually trigger a deployment from your dashboard if the build queue has stalled.
|
|
</Accordion>
|
|
|
|
<Accordion title="I can't find a branch in the editor">
|
|
The branch dropdown in the editor shows all branches in your connected repository. If a branch is missing:
|
|
|
|
- **The branch was deleted**: Merged or deleted branches no longer appear in the list.
|
|
- **The branch was created locally but not pushed**: Branches only appear after they're pushed to your remote repository.
|
|
- **You're connected to the wrong repository**: Go to [Git Settings](https://app.mintlify.com/settings/deployment/git-settings) to verify which repository the editor is connected to.
|
|
</Accordion>
|
|
|
|
<Accordion title="The live preview in the editor doesn't match the published site">
|
|
The editor's built-in preview renders pages as closely as possible to the published output, but minor visual differences can occur. For an exact preview:
|
|
|
|
1. Save your changes to a feature branch.
|
|
2. Open the preview deployment URL from the publish menu. The format is `organization-branch-name.mintlify.app`.
|
|
|
|
Preview deployments render identically to the live site and update automatically each time you save to the branch.
|
|
</Accordion>
|
|
|
|
</AccordionGroup>
|
|
|
|
If none of these steps resolve your issue, contact [Mintlify support](https://mintlify.com/docs/contact-support).
|