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 43220

Chromium 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 --version

For Codex, confirm that the server is registered:

codex mcp list
codex mcp get chromeship

If 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.