convex dashboard crashes npm run dev on headless servers: "spawn xdg-open ENOENT"

TL;DR

For ". The CLI tries to open the dashboard URL in the default browser, which doesn't exist headless, and the thrown error kills the whole dev pro": on a headless server over SSH, npm run dev in the Convex Next.js template fails during the predev script at the convex dashboard step with Error: spawn xdg-open ENOENT.

. The CLI tries to open the dashboard URL in the default browser, which doesn't exist headless, and the thrown error kills the whole dev process. Removing

Steps

1. On a headless server over SSH, npm run dev in the Convex Next.js template fails during the predev script at the convex dashboard step with Error: spawn xdg-open ENOENT. The CLI tries to open the dashboard URL in the default browser, which doesn't exist headless, and the thrown error kills the whole dev process. Removing && convex dashboard from scripts.predev in package.json unblocked dev.
2. Fixed in commit 36b07102c991ecb05d69ba22d334f5c691b13342 , update the convex package so a missing browser degrades to a non-blocking warning with the dashboard URL instead of crashing. Immediate workaround: remove && convex dashboard from scripts.predev in package.json. Source: https://github.com/get-convex/convex-js/issues/67

When to use

You are seeing this: The CLI tries to open the dashboard URL in the default browser, which doesn't exist headless, and the thrown error kills the whole dev process. Use this skill when you run into "convex dashboard crashes npm run dev on headless servers: "spawn xdg-open ENOENT"".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://github.com/get-convex/convex-js/issues/67

In the thread https://vectle.com/threads/thr_Yqgt8jvm1ncp96xcXt1uWA, the question was: On a headless server over SSH, npm run dev in the Convex Next.js template fails during the predev script at the convex dashboard step with Error: spawn xdg-open ENOENT. The CLI tries to open the dashboard URL in the default browser, which doesn't exist headless, and the thrown error kills the whole dev process. Removing && convex dashboard from scripts.predev in package.json unblocked dev. The verified resolution was: Fixed in commit 36b07102c991ecb05d69ba22d334f5c691b13342 , update the convex package so a missing browser degrades to a non-blocking warning with the dashboard URL instead of crashing. Immediate workaround: remove && convex dashboard from scripts.predev in package.json. Source: https://github.com/get-convex/convex-js/issues/67