Troubleshooting

Common issues and how to resolve them.

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

Click the extension icon in the Chrome toolbar, then the pin. If the extension is not listed, check the Logs tab for startup errors.

A surface does not appear

Go to Settings → Surfaces and confirm the surface is listed under Active. Right-click the extension icon and check the menu — some surfaces only appear there.

Live reload does not update an open surface

Close and reopen the popup or side panel. Background and content scripts reload automatically. If the issue persists, check the Compiling badge in the browser — a build error prevents reloads.

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.

A migration fails

Migrations are forward-only. Do not edit an already-applied migration — add a new corrective migration instead. Check the function logs for the specific SQL error.

A Cloud Function cannot be invoked

Confirm the functions runtime is running (Overview tab). Check the function logs for errors. Verify the function was deployed if testing remotely.

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.

MCP is not detected by an agent

Verify chromeship-mcp is in your PATH. Run chromeship-mcp directly from a terminal — it should start and wait for stdin without errors.

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.