Common issues and solutions when developing with or contributing to Quark.
docker compose down -v # Remove stopped containers and volumes
docker compose up -d # Restart freshIf port 5432 or 6379 is already in use by a local process:
lsof -i :5432 # Find what's using Postgres port
lsof -i :6379 # Find what's using Redis portKill the conflicting process or change the port mapping in docker-compose.yml.
Ensure the SMTP_HOST in your .env points to localhost and SMTP_PORT is 1025. Open http://localhost:8025 to view captured emails.
If a Docker, Railway, or other container deployment boots but health checks fail or requests never connect, the standalone Next.js web server is probably bound to localhost inside the container.
Set:
HOSTNAME=0.0.0.0Then use the standalone web entrypoint (pnpm --dir apps/web start:deploy in scaffolded apps) and let the platform inject PORT when possible. Quark's generated web Dockerfile and Railway config already set HOSTNAME=0.0.0.0; this usually only breaks when the start command or environment was customized.
PrismaClientInitializationError on startupThe database URL is wrong or Postgres is not running.
DATABASE_URL in your .env matches docker-compose.ymldocker compose ps to confirm postgres is Uppnpm db:migrate to ensure migrations are appliedAfter editing prisma/schema.prisma, always regenerate the client:
pnpm db:generateIf you added a new model, also run:
pnpm db:migrateP2002 Unique constraint violation in testsTests that create database records may collide if they share email addresses or other unique fields. Use unique values per test run (e.g. email: \test-\${Date.now()}@example.com\``).
/login on every requestThe session cookie is missing or expired. Check:
AUTH_SECRET in .env is set (min 32 characters)NEXTAUTH_URL matches the URL you're accessing the app fromOAuthCallbackErrorhttp://localhost:3000/api/auth/callback/<provider>GITHUB_ID/GITHUB_SECRET, or GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET, are correct in .envemail_verified claim is not confirmed, because the sign-in creates its account on first sight. An unconfirmed address is refused with no detail on the error page, by design.auth.js registers a NextAuth provider only when both halves are present — a client id without its secret, or a secret without its id, registers nothing and the button silently disappears. Startup logs a warning naming the provider and the missing half.
The mobile app posts to /api/auth/google and /api/auth/apple, which verify the token themselves rather than going through NextAuth. Set GOOGLE_CLIENT_ID and APPLE_CLIENT_ID on the server.
Google's client id must match the app's EXPO_PUBLIC_GOOGLE_CLIENT_ID — they are the same OAuth client, registered in one console. Apple has no mobile-side id: the native flow's audience is the app's bundle identifier, so APPLE_CLIENT_ID on the server takes that bundle id, the Services ID (web flow), or both comma-separated.
Three distinct failures, told apart by status:
503 Google sign-in is not configured on this server / 503 Apple sign-in is not configured on this server — the client id is unset (or blank). The endpoint is off. Nothing about the token matters; fix the server config.401 Invalid Google token — the token is genuine but its aud is not this app's client id. Almost always a client-id mismatch between the mobile app and the server.400 on Apple — the request omitted nonce. It is required, not optional. (A token that arrives with no nonce claim, or a stale one, is a 401 instead — see below.)Both routes return the same generic 401 for every verification failure — a token the provider rejected, an audience that does not match, an address the provider has not verified, and on Apple also a missing or replayed nonce — deliberately, because distinguishing them tells a caller which check to work around. Diagnose per provider:
GOOGLE_CLIENT_ID and compare it against the mobile app's EXPO_PUBLIC_GOOGLE_CLIENT_ID. They must be the same OAuth client, registered once in Google Cloud Console. If they match, check that the account's address is verified — Google issues tokens for unconfirmed addresses (some Workspace accounts, newly created accounts before the round-trip completes), and this route refuses them because it would otherwise create the account without proof anyone can read the inbox.APPLE_CLIENT_ID is not read from any mobile env var. The bundled iOS client signs in with the native flow, so Apple stamps the token's aud with the app's bundle identifier (com.quark.app, in apps/mobile/app.json). The Services ID applies only to the web flow. Set APPLE_CLIENT_ID to the bundle ID, or to both comma-separated when web and native flows both run. If the audience matches and sign-in still 401s, suspect a stale or replayed nonce — the client must generate a fresh one per attempt.All mutating requests (POST, PUT, PATCH, DELETE) must include the CSRF token. Use withCsrfProtection on API routes and send the token that getCsrfToken() returns, imported from @usequark/quark-core/csrf-client.
Two failure modes account for most reports:
CSRF token not found — the request carried no csrf_token cookie. Either GET /api/csrf was never called, or the cookie was dropped. The cookie is SameSite=Strict, so it is also absent from any cross-site request; that is the protection working, not a bug.Invalid CSRF token — the header and cookie disagreed. Usually a token cached in client state that has outlived the cookie's one-hour maxAge. getCsrfToken() refetches before this can happen; hand-rolled caching needs to do the same, or call clearCsrfToken().MissingEnvError on startupA required environment variable is not set. The error message names the missing variable. Check your .env file against .env.example.
The config package uses Zod for validation. If a variable exists but has the wrong format (e.g. PORT=abc), you'll see a Zod parse error. Check the type expectation in packages/config/src/environment.js.
429 Too Many Requests during developmentRate limiting uses Redis. If you're hitting limits during dev, temporarily increase the limit in packages/config/src/environment.js or set RATE_LIMIT_MAX in your .env.
Ensure REDIS_URL is set in your production environment. Rate limiting silently no-ops when Redis is unavailable to avoid blocking legitimate requests, but this means limits are not enforced.
CORS is enforced in apps/web/src/proxy.js, and the origin list is resolved in packages/config/src/app-url.js. The canonical origin comes from APP_URL; add extras with ALLOWED_ORIGINS (comma-separated, production) or NEXT_DEV_ALLOWED_ORIGINS / ALLOWED_DEV_ORIGINS (development hosts). For a local frontend on another port, add its origin rather than replacing the default.
OPTIONS requests returning 405All API routes that use withCsrfProtection handle OPTIONS automatically. If you have a custom route, add an explicit OPTIONS export or use the Quark withCors helper.
422 Unsupported Media Type on file uploadThe file type or size exceeds configured limits. Check validateFile defaults in @usequark/quark-core. Common causes:
UPLOAD_MAX_SIZE (default 10 MB, read by packages/core/src/file-validation.js). The request-body cap is a separate UPLOAD_SIZE_LIMIT in apps/web/src/proxy.jsThe default local storage provider writes to .quark-storage/ in the project root. This directory persists across restarts. If files are missing, check that the directory exists and was not deleted.
AccessDeniedVerify the following in your .env:
STORAGE_PROVIDER=s3STORAGE_PROVIDER is s3 (not r2) and S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_REGION are correct. For R2 or MinIO also set S3_ENDPOINT. The credential variable names are always the S3_* pair; there is no AWS_* variants3:PutObject and s3:GetObject permissions on the target bucketBiome is installed as a dev dependency. Run pnpm install from the monorepo root.
Install the Biome VS Code extension and ensure editor.formatOnSave is enabled. Check that .vscode/settings.json sets "editor.defaultFormatter": "biomejs.biome".
import ordering errorsBiome enforces import order. Run pnpm lint to auto-fix, or use the Biome VS Code extension to fix on save.
The scaffold templates in packages/cli/templates/ are out of date. After changing any source file in apps/web/, apps/worker/, packages/db/, packages/config/, packages/ui/, or packages/jobs/, run:
pnpm --filter @usequark/quark-create-app sync-templatesThen commit the updated templates along with your source changes.
sync-templates overwrites a file I edited manuallyFiles listed as TEMPLATE_ONLY in packages/cli/scripts/sync-templates.js are never overwritten. If you need to protect a file from sync, add it to that list.
The CLI packages templates at publish time. To get updated templates, upgrade the CLI:
npm install -g @usequark/quark-create-app@latest
npx @usequark/quark-create-app my-appError: connect ECONNREFUSED in testsTests require a running Postgres and Redis instance. Start them with:
docker compose up -dCheck that CI has the docker-compose.yml services running. The GitHub Actions workflow uses services: to start Postgres and Redis automatically. Verify the DATABASE_URL and REDIS_URL environment variables are set correctly in CI.
ERR_MODULE_NOT_FOUNDYou may have a missing or misspelled package import. Run pnpm install and pnpm db:generate to ensure all dependencies are present.
Co-locate test files (*.test.js) next to the source file. Root pnpm test runs node --test 'scripts/*.test.mjs' && turbo run test; each workspace's own test script delegates to scripts/run-tests.mjs <dir>, which discovers the co-located files. A directly-run workspace suite therefore needs pnpm db:generate first when it touches Prisma, because turbo run test normally handles that dependency.