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.

Docker is installed but unavailable

Open Docker Desktop. Wait for the engine to start (the whale icon stops animating). Then restart the functions runtime from the Studio.

Supabase startup fails

In the Functions tab, click Stop stack, then Start. If the error persists, check that Docker is running and the project has the Supabase integration enabled.

Database schema issues

Create a new SQL migration that corrects the schema, then restart the local backend. Do not delete an already-applied migration to undo a change. For production, deploy the corrective migration from Functions.

A Supabase function cannot be invoked

Confirm the Supabase runtime is active for this project and inspect its function logs. For production calls, verify the function was deployed and the extension build uses production Supabase values.

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.