Troubleshooting
Start with the visible symptom, check the matching logs, and recover without bypassing ChromeShip's managed workflow.
ChromeShip Studio does not open
Check that the terminal shows the Studio URL. If the port is in use, ChromeShip prints an error. Try a different port:
chromeship dev --port 43220Chromium does not load the extension
Check the runtime logs first. ChromeShip closes a managed browser that opens without a valid unpacked extension, so a missing extension usually points to a build or launch error.
A surface does not appear
Open Settings > Surfaces and confirm the surface is active. Popup opens from the toolbar icon; side panel may also appear in the extension menu; options and new tab have their own entry points.
Live reload does not update an open surface
Popup and side panel may need to be reopened after Chrome destroys their page context. Background and content scripts reload automatically. If nothing updates, read the build output in Logs.
A production build fails validation
Check that production environment values are set for every variable marked as required. Review permissions — some Chrome Web Store policies limit certain permissions. If the error mentions the extension name or description length, the Chrome Web Store caps manifest.json's name at 75 characters and its description at 132 — shorten it in Settings → General (or the matching translation key if you've localized it).
MCP is not detected by an agent
Verify that the ChromeShip MCP command is installed:
chromeship-mcp --versionFor Codex, confirm that the server is registered:
codex mcp list
codex mcp get chromeshipIf it is missing, run codex mcp add chromeship -- chromeship-mcp. Restart your agent and open a new task after changing MCP configuration. If the ChromeShip command itself is unavailable, reinstall ChromeShip globally.
A license cannot be activated
Confirm your license key is correct. Activation requires internet access. One license covers three machines — if you need to deactivate an old machine, contact support.
Next steps
Still stuck? Contact support. Set up MCP for AI-assisted development, or check the Getting Started guide for a fresh start.
