Local development

The first failing step usually points to the right configuration: environment validation, Cloudflare account access, database setup, or a browser request. Start with that error and the corresponding section below.

Fix missing or stale environment values

Wrangler loads Worker secrets separately from Vite's public build settings. A stale .dev.vars takes precedence over environment files for Worker secrets.

For the normal setup, keep .env.local copied from .env.example and remove or rename an old .dev.vars. If you deliberately use .dev.vars, keep Worker secrets there and public VITE_* values available to Vite.

Restart development after a change. Use pnpm env to check validation, and confirm required values exist without printing their contents. The environment guide covers the source settings.

Connect remote Cloudflare services

AI and Flagship connect to your Cloudflare account during local development. Authenticate with Wrangler or provide an appropriate API token, and connect your own resources.

pnpm exec wrangler login

The browser test harness isolates these integrations, so a passing browser test does not verify normal development's remote access.

A flag always returns its fallback

A fallback value can indicate an evaluation failure. Check the Flagship app, flag key, value type, and credentials against your feature flag configuration.

Verify the dashboard value as well as the result in the app.

The AI interface loads but does not respond

The interface can load before the model is configured. Check model access, gateway settings, provider credentials or usage balance, and the Worker and gateway logs.

The AI guide explains the setup, and the model recipe covers another provider or direct Workers AI.

Fix local sign-in and cookies

Keep the public app URL, auth URL, and browser origin aligned, including protocol and port. If you use another port, update the URL values and OAuth callbacks together, then clear old cookies if needed.

Use the existing auth configuration and cookie integration when customizing sign-in. See OAuth and account settings.

Regenerate missing types and content

Edit the source and regenerate its output. Changes made directly to generated files are replaced by the next compilation.

Find local email output

Local sending is simulated. Inspect development output and use pnpm email to preview templates. Real inbox delivery needs a verified sender and production service access; see email sending.

For tables and test credentials, use database troubleshooting. For production-only issues, use deployment troubleshooting.