Troubleshooting
Almost every failure here names what is wrong. Match the message, apply the fix.
Configuration
Section titled “Configuration”| Message | Fix |
|---|---|
site.config.ts is invalid (N issues) |
Each issue reads site.config.ts › <path>: <message>. Re-run pnpm check:config. |
"blog" is a reserved path segment |
routes.listingBase cannot be blog or search. Full list |
must be a CSS value, not a Tailwind class name |
theme.tokens takes raw CSS: 'oklch(0.55 0.2 260)', not 'bg-blue-600'. Theming |
The build stops
Section titled “The build stops”| Message | Cause and fix |
|---|---|
unknown category "marketing" |
category must match one of your categories[].slug values. pnpm listings:import reports it per row. |
N orphan listing(s) with fewer than 2 inbound links |
seo.strictLinks: true. Give the listing a tag it shares with another, or set seo.strictLinks: false. |
| Over the file budget | Fails above 90% of the plan limit, warns above 80%. Turn off seo.ogScope.pseo, then seo.ogImages: 'static'. Cost and limits |
| An unexpected script | A component that hydrates, or a <script src> on a content page. /search/ is exempt. |
must match pattern /^(https:\/\/|\/)/ |
A rejected logo. Use an https:// URL or a /-rooted path (/logos/acme.svg); ./acme.png fails. Listings and datasets |
unknown tag(s) "no-code" filtered |
The tag is not in site.config.ts tags, so it is dropped, not fatal — but it may have been the listing’s only inbound link, and then seo.strictLinks trips. |
Development
Section titled “Development”| Symptom | Cause and fix |
|---|---|
Search finds nothing under pnpm dev |
Pagefind indexes only during a real build: “Search is not available yet.” Run pnpm build, then pnpm preview. |
| A class renders unstyled | global.css uses an @source allow-list; a class from an unlisted directory is never generated, silently. Add the directory. |
| A custom field renders nothing | Objects and arrays are skipped with no warning. Scalars render. |
listings loader: the local database has no listings table |
Nothing has created the local database the build reads. Run pnpm dev once — migrations, then the demo seed — or pnpm db:migrate:local && pnpm db:seed:local. |
Deploy
Section titled “Deploy”| Symptom | Fix |
|---|---|
| Canonicals point at the wrong domain | site.url is baked in at build time — canonicals, sitemap, feeds and OG image URLs. Fix it and build again. |
pnpm check type-errors on a binding |
pnpm cf:typegen after any change to wrangler.jsonc or the binding set. |
| The deploy differs from what you built | Two deploy paths racing. Once Workers Builds is connected, stop running pnpm deploy by hand. |
Stripe reports failed deliveries
Section titled “Stripe reports failed deliveries”The Stripe webhook URL needs its trailing slash: https://example.com/api/stripe/webhook/; without
it Cloudflare answers 308. Same for the Deploy Hook URL.
Deploy
Once the endpoint is reached, the webhook answers for itself:
| Answer | Cause |
|---|---|
400 {"error":"invalid signature"} |
The wrong STRIPE_WEBHOOK_SECRET |
503 {"error":"payments are not configured"} |
Payments on without a provider |
404 {"error":"not found"} |
features.payments is off |
| 405 | Anything but a POST |
At run time
Section titled “At run time”Secrets and providers
Section titled “Secrets and providers”| Message | Effect, then fix |
|---|---|
admin.emails is empty: nobody can sign in to /admin/ |
/admin/ shows “Admin is not set up”. Name an address in site.config.ts — admin: { emails: ['you@acme.com'] }, with features.accounts: true — and deploy. Admin |
TOKEN_SECRET is still the value from .env.example |
Every status and checkout link is forgeable. node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))", put it in .env.prod, then pnpm cf:secrets TOKEN_SECRET. Environment and secrets |
Missing secret TOKEN_SECRET |
/submit/ refuses. pnpm cf:secrets TOKEN_SECRET. Environment and secrets |
Missing secret STRIPE_SECRET_KEY, Missing secret STRIPE_WEBHOOK_SECRET |
One key without the other degrades the provider to none. pnpm cf:secrets STRIPE_SECRET_KEY STRIPE_WEBHOOK_SECRET. Plans and payments |
Missing secret RESEND_API_KEY |
Degrades to console: rows read sent and nothing leaves. pnpm cf:secrets RESEND_API_KEY |
providers.email is "console" |
Mail is logged, not sent. Set providers.email to 'cloudflare' or 'resend', with providers.emailFrom. Email |
Missing secret DEPLOY_HOOK_URL |
Approving builds nothing; /admin/ offers Publish now. Create the Deploy Hook in Workers Builds, then pnpm cf:secrets DEPLOY_HOOK_URL |
Missing secret GITHUB_TOKEN, Missing secret GITHUB_REPO |
'github-dispatch' needs both. pnpm cf:secrets GITHUB_TOKEN GITHUB_REPO |
providers.rebuild is "none" |
Approved listings stay off the site. pnpm deploy after approving, or switch to 'deploy-hook'. Publishing on approval |
Statuses and messages
Section titled “Statuses and messages”| Answer or message | Cause and fix |
|---|---|
503 Payment is temporarily unavailable |
A Stripe key or TOKEN_SECRET is missing, or Stripe refused the session. A bad token, an unknown listing, a free tier or payments off answer 404 instead. |
redirect_uri_mismatch |
Register https://<your domain>/auth/google/callback/, trailing slash included. Locally site.url must be the browser’s origin, and the schema takes only https://. Submitter accounts |
403 “Not an admin” or “Prove this address first” at /admin/login/ |
The signed-in address is not in admin.emails, or is listed but not proven yet: sign in with Google, or open a password-reset link. Security |
cloudflare E_SENDER_NOT_VERIFIED in last_error |
The sending domain is not enabled, or the account is not on Workers Paid. Run pnpm exec wrangler email sending enable <domain>, or switch to Resend. |
| A submission vanished after the honeypot | By design: a filled honeypot returns the same 303 to /submit/?sent=1 and banner, and writes nothing. |
That address has submitted N times in the last 24 hours, which is the limit. |
limits.submissionsPerEmailPerDay. The submission form |
Mail is marked sent but never arrives
Section titled “Mail is marked sent but never arrives”providers.email: 'cloudflare' without the EMAIL binding in wrangler.jsonc, or 'resend'
without its key, both degrade to the console provider.
pnpm exec wrangler d1 execute DB --remote --command "SELECT template, status, attempts, last_error, sent_at FROM email_outbox ORDER BY created_at DESC LIMIT 5"A sent row with a sent_at and no mail confirms it. Restore the binding or the key,
pnpm cf:typegen, deploy.
404 on /dashboard/, /login/, /signup/, /api/newsletter/ or /out/
Section titled “404 on /dashboard/, /login/, /signup/, /api/newsletter/ or /out/”| Path | Needs |
|---|---|
/dashboard/ and the pages under it, /login/, /login/dialog/, /login/forgot/, /signup/, /auth/reset/, /api/bookmarks/<id>/ |
features.accounts: true; /auth/google/ redirects to /login/ instead, and /account/ is a permanent redirect to /dashboard/ |
/api/newsletter/ |
features.newsletter: 'd1' |
/out/<id>/ |
features.clicks: 'ping' or 'redirect' |
/advertise/ |
ads.page.enabled: true; the page is not built while it is false |
/submit/ is not gated by features.submissions; that flag only controls the header and
footer links.
The hourly jobs did not run locally
Section titled “The hourly jobs did not run locally”Astro’s dev server does not run scheduled(); under pnpm dev the scheduled URL is the 404 page:
pnpm build && pnpm exec wrangler devcurl "http://localhost:8787/cdn-cgi/local/scheduled?cron=0+*+*+*+*"wrangler’s log then shows one jobs: expireFeatured=… flushOutbox=… … line.
Admin
The build fails naming D1_READ_TOKEN or another D1 variable
Section titled “The build fails naming D1_READ_TOKEN or another D1 variable”A builder reads the real database and needs all three credentials — Workers Builds → Settings →
Build variables, D1_READ_TOKEN as a secret, or pnpm cf:ci from .env.prod. With a partial set:
listings loader: CLOUDFLARE_ACCOUNT_ID, D1_DATABASE_ID are set but D1_READ_TOKEN is not set. …With none, a builder has no local database to fall back to and stops on
the local database has no listings table instead. D1_READ_TOKEN is an account API token with
“D1 Read” on this database — not the Workers Builds deploy token, not CLOUDFLARE_API_TOKEN.
Locally the same rule holds: all three in .env read the real database, none of them the local one
under .wrangler/state/; pnpm cf:doctor’s build-database line says which a build here reads.
The build’s database