npx convex fails with “could not resolve ‘@auth/core’ using convex Auth + local run

by

Summary

A local Convex development server failed to start because the bundler could not resolve @auth/core, even though Convex Auth was selected during project creation. The failure occurs during Convex’s component-definition bundling step, not during normal React/Vite execution. The root issue is a mismatch between Convex Auth’s server-side expectations and the local environment’s module resolution.

Root Cause

The failure stems from Convex Auth’s server bundle expecting @auth/core to be present, even though the generated project does not install it by default. When npx convex dev bundles server functions, it attempts to import:

import { setEnvDefaults } from "@auth/core";

This import fails because:

  • @auth/core is not installed automatically in some template versions.
  • Convex’s server bundler does not fall back to optional peer dependencies.
  • Local dev mode is stricter than cloud deployments, so the error appears only locally.

Why This Happens in Real Systems

This pattern is common in modern JavaScript toolchains:

  • Peer dependencies are often not auto-installed, leading to missing modules.
  • Bundlers behave differently between dev, prod, and cloud environments.
  • Template generators lag behind library updates, causing mismatches.
  • Auth libraries evolve quickly, and Convex Auth depends on upstream Auth.js packages.

Real-World Impact

When this issue appears, developers experience:

  • Local dev server fails to start, blocking iteration.
  • Confusion between Convex cloud vs. local behavior, since cloud dev may work.
  • Misleading suggestions like “mark as external,” which do not solve the underlying dependency gap.
  • Time wasted reinstalling node_modules without effect.

Example or Code (if necessary and relevant)

A correct installation step that resolves the missing dependency:

npm install @auth/core @auth/sveltekit @auth/nextjs

Or, for minimal Convex Auth usage:

npm install @auth/core

How Senior Engineers Fix It

Experienced engineers approach this by validating the dependency chain:

  • Check Convex Auth documentation for required peer dependencies.
  • Inspect the failing import path inside node_modules/@convex-dev/auth/....
  • Install missing peer dependencies explicitly, even if templates should have done so.
  • Pin versions to avoid mismatches between Convex Auth and Auth.js.
  • Clear bundler caches only after verifying dependency correctness.

A reliable fix is:

  • Install the missing dependency:
    • npm install @auth/core
  • Ensure Convex Auth version matches the expected Auth.js version.
  • Re-run npx convex dev.

Why Juniors Miss It

Less experienced developers often struggle because:

  • They assume template-generated projects always include all required dependencies.
  • They expect npm to auto-install peer dependencies, which it does not.
  • They misinterpret bundler errors as Vite/React issues, not Convex server issues.
  • They rely on cloud dev working, not realizing local bundling is stricter.
  • They try deleting node_modules instead of inspecting the actual import failure.

Juniors tend to focus on symptoms (broken dev server) rather than the underlying cause (missing peer dependency), while seniors trace the dependency graph and fix the root mismatch.

Leave a Comment