Troubleshooting

This page covers common development issues you may run into when working on the Muse & Co codebase, along with their causes and fixes.

Quick Reference: Common Errors

Error	Likely Cause	Fix
Cannot find module or Module not found	Missing dependencies	Run pnpm install from the repo root
Node.js version mismatch	Wrong Node version	Use Node.js 20 or later (node -v to check)
D1_ERROR: no such table	Migration not run on target DB	Run the migration with --remote flag (see below)
Error: No D1 databases configured	Missing wrangler.toml binding	Add the [[d1_databases]] block to wrangler.toml
Pages deployment failed	Build output missing or wrong directory	Deploy with the project's ./deploy.sh, which builds and checks dist/
Secret not found	Environment variable not set	Use npx wrangler secret put SECRET_NAME
CORS error in browser	API not returning CORS headers	Check that the API route includes proper CORS headers
Stripe webhook signature invalid	Wrong webhook secret	Verify STRIPE_WEBHOOK_SECRET matches the Stripe dashboard

Build Failures

Node.js Version

The codebase requires Node.js 20 or later. Check your version:

node -v

If you need to update, use your preferred version manager (nvm, fnm, etc.):

nvm install 20
nvm use 20

Clean Install

When dependencies get into a bad state, a clean install usually fixes things:

# From the project root (e.g., muse-customer/, muse-admin/, or muse-wiki/)
rm -rf node_modules
rm -rf node_modules
pnpm install   # from the repo root; never create package-lock.json

TIP

If you are working across multiple projects in the monorepo, run pnpm install from the repo root; it installs every workspace. This repo uses pnpm only.

TypeScript Errors

To check for TypeScript issues without building:

npx tsc --noEmit

This will report all type errors. Fix them before attempting a build or deployment.

Database (Cloudflare D1) Issues

Local vs. Remote

D1 has two modes: local (for development) and remote (production). Most issues come from targeting the wrong one.

Command	Target
npx wrangler d1 execute muse-and-co-db --command="..."	Local D1 (default)
npx wrangler d1 execute muse-and-co-db --remote --command="..."	Production D1

WARNING

Always use --remote when you intend to query or modify the production database. Without it, you are working against a local SQLite file that has nothing to do with production.

Running Migrations

npx wrangler d1 execute muse-and-co-db --remote --file=migrations/XXXX_migration_name.sql

Checking Table Structure

npx wrangler d1 execute muse-and-co-db --remote --command="SELECT sql FROM sqlite_master WHERE type='table' AND name='your_table_name';"

Wrangler.toml Binding

Make sure your wrangler.toml includes the D1 database binding:

[[d1_databases]]
binding = "DB"
database_name = "muse-and-co-db"
database_id = "your-database-id-here"

If this block is missing, Workers and Pages Functions will not be able to access D1.

Deployment Issues

Cloudflare Pages Build Logs

When a deployment fails, check the build logs:

1. Go to dash.cloudflare.com
2. Select the project (muse-customer, muse-admin, or muse-wiki)
3. Click on the failed deployment
4. Read the build log output for error details

Verifying Build Output

Before deploying, make sure the build actually produced output:

pnpm run build
ls dist/

You should see index.html and asset files. If dist/ is empty or missing, the build failed silently -- check for errors in the build command output.

Pages Functions (API Routes)

If API routes are not working after deployment:

• Verify that the functions/ directory exists in the project root
• Check that function file names match the expected route paths
• Look at the Functions tab in the Cloudflare Pages dashboard for runtime errors

Local Development

Starting the Dev Server

For Pages projects (customer portal, admin portal):

pnpm exec wrangler pages dev -- pnpm run dev

For Workers:

npx wrangler dev

INFO

wrangler pages dev proxies requests through Cloudflare's local runtime, which gives you access to D1 bindings, R2, and other Cloudflare services locally. Running pnpm run dev alone (Vite only) will not have access to these bindings.

Don't pass a static directory (e.g. dist) alongside the proxy command -- when both are given, wrangler silently ignores the proxy command and just serves the static directory instead.

Environment Variables and Secrets

For local development, create a .dev.vars file in the project root:

STRIPE_SECRET_KEY=sk_test_...
AWS_SES_ACCESS_KEY=...
SESSION_SECRET=...

For production, set secrets via the CLI:

npx wrangler secret put SECRET_NAME

Or set them in the Cloudflare dashboard under the project's Settings > Environment Variables.

WARNING

Never commit .dev.vars or .env files to git. They should already be in .gitignore, but double-check if you create a new project.

Stripe Issues

Webhook Signature Failures

If Stripe webhooks are returning 400 errors:

1. Confirm the webhook endpoint URL in the Stripe dashboard matches your deployment
2. Verify the STRIPE_WEBHOOK_SECRET environment variable matches the signing secret shown in Stripe
3. Check that the webhook is listening for the correct event types

Test vs. Live Mode

Stripe has separate API keys for test and live modes. Make sure you are using the correct keys:

Environment	Key Prefix
Local / Development	sk_test_...
Production	sk_live_...

Email (AWS SES) Issues

If transactional emails are not sending:

• Verify SES credentials (AWS_SES_ACCESS_KEY, AWS_SES_SECRET_KEY) are set
• Check that the sending domain or email address is verified in the SES console
• Look at the SES sending statistics for bounces or complaints

---

Last updated: July 2026