Troubleshooting

Start with the command closest to the failure. StarryBio validates configuration during pnpm dev and pnpm build, so the terminal’s exact field path is normally the most useful diagnostic.

Do not include private hosting credentials, API tokens, or anything you do not want published when asking for help.

pnpm dev or pnpm build fails with an invalid configuration error

Symptoms: The command stops with Invalid StarryBio config and a dotted path such as sections.0.links.1.url.

Likely causes:

• An unsupported or misspelled field is present. The schema rejects unknown fields.
• A required value is missing: a link label, regular-link URL, copy-link value, profile field, or section array.
• A value uses an invalid URL, color, date/time, timezone, analytics ID, or output extension.
• Old v2 property names remain.

Diagnose and fix:

1. Run pnpm validate by itself to reduce noise.
2. Find the reported path in config/starrybio.config.ts.
3. Compare it with Configuration Reference and the relevant feature page.
4. Remove unknown keys rather than hoping they will be ignored.
5. For a v2 config, use the migration table in Operations and Updates.

Examples: links must now be inside sections; text became label; bright became classic-blue; showLocalTime became showVisitorTime.

Validation says a local asset is missing or outside public/

Symptoms: pnpm validate reports that profile.image, favicon, an icon, or another asset does not exist, or must stay under public/.

Likely causes: The file was not added, the path includes public/ twice, letter casing differs, a backslash/path traversal was used, or a generated asset is expected before its generator runs.

Fix:

1. Place the source file under public/, for example public/assets/images/avatar.webp.
2. Refer to it as assets/images/avatar.webp or /assets/images/avatar.webp.
3. Run pnpm validate again.
4. For og.png, qr.png, or contact.vcf, verify the matching generator is enabled, then run pnpm build; do not manually rely on an ignored generated file.

See Assets and Generated Downloads.

Simple Icon generation fails

Symptoms: pnpm dev, pnpm build, or pnpm icons reports an unknown Simple Icon.

Likely cause: The inferred slug from simpleIcon/brand does not match the pinned simple-icons package’s filename.

Fix: Set an exact lowercase slug in the icon configuration:

icon: { simpleIcon: 'Node.js', slug: 'nodedotjs' }

Run pnpm icons after changing it. Do not edit generated files in public/assets/icons/simple-icons/; the next generator run replaces them.

QR, Open Graph image, or vCard is missing

Symptoms: The page does not show a download action, a download 404s, or the build errors while generating an asset.

Likely causes and fixes:

• enabled is false: set the relevant ogImage, qr, or contactCard setting to true.
• QR URL is unavailable: set qr.url, or set seo.canonicalUrl for the fallback.
• vCard fails validation: provide name plus at least one of email, phone, or website.
• Output path is invalid: use a path below public/; OG/QR output needs .png or .svg, contact-card output .vcf.
• Stale expectation: disabled generators intentionally remove old output at build time.

Run pnpm build, inspect dist/, and use pnpm preview before redeploying. See Assets and Generated Downloads.

The status is wrong or does not change

Symptoms: A visitor sees an unexpected current state, a schedule dialog has unexpected times, or “Next available” is absent.

Likely causes:

• Schedules are evaluated in each visitor’s local timezone, not ownerTimeZone.
• An overnight range is being interpreted incorrectly.
• Multiple matching entries overlap; the first matching schedule item wins.
• The expected status key is not exactly available, so the next-availability lookup has no matching entry.
• The current state is the default because no interval matches.

Fix: Test the schedule with the viewer’s local date/time, put more specific intentional matches first, use end as an exclusive boundary, and review the overnight examples in Availability and Announcements. ownerTimeZone only displays the owner clock; it never changes matching.

An announcement keeps returning or does not reappear

Symptoms: A dismissed announcement returns, or a changed announcement stays hidden.

Diagnosis: Dismissal is a seven-day starrybioAnnouncement cookie whose key is derived from the announcement’s text and URL.

Fix: To intentionally show a new announcement again, change its text or url and deploy. To test a dismissal again, use a fresh/private browser context or clear the site cookie. To retire it, set announcement.enabled: false and deploy.

The deployed site loads but assets, analytics, or a custom script fail

Symptoms: Images, fonts, scripts, or analytics requests fail in the browser console; the console mentions Content Security Policy.

Likely causes: Generated headers are stale, the remote URL is wrong, or an HTTP resource is blocked on the HTTPS site.

Fix:

1. Use the browser Network and Console tabs to identify the exact blocked URL and directive.
2. Use HTTPS for external resources.
3. Run pnpm headers after changing analytics, then rebuild.
4. Keep the existing restrictive policy; do not add broad wildcards or unsafe-inline.
5. Run pnpm preview, use pnpm preview:cloudflare if applicable, then deploy and retest the canonical domain.

See SEO and Analytics and Security and Privacy.

pnpm deploy cannot authenticate or deploys to the wrong account

Symptoms: Wrangler reports unauthenticated/unauthorized access, cannot find an account, or deploys under an unexpected account.

Fix:

pnpm exec wrangler whoami
pnpm exec wrangler login
pnpm exec wrangler whoami

Complete the login in the intended account. Check wrangler.jsonc for the Worker name; the current project has no explicit account ID, bindings, or secrets to repair. In CI, review the CI authentication setup without printing its token.

pnpm deploy intentionally remains the Cloudflare compatibility command. GitHub Pages, Vercel, and Netlify use repository-triggered deployments; inspect the connected repository, production branch or workflow, and provider build log instead of running this command for those hosts.

The Worker deploys but the custom domain is not working

Symptoms: The workers.dev address works but the custom domain fails, shows another application, or cannot be added in Cloudflare.

Likely causes: The zone is not active or is not Cloudflare-nameserver managed, the hostname has a conflicting CNAME, a normal Worker route conflicts with a Custom Domain, DNS/TLS provisioning is still in progress, or the wrong hostname was put in the site’s canonical metadata.

Fix:

1. Confirm the zone is active in Cloudflare and Cloudflare controls its nameservers.
2. In Workers & Pages > your Worker > Settings > Domains & Routes, inspect existing routes and custom domains.
3. Remove/replace the conflicting DNS CNAME before adding a Custom Domain; do not delete unrelated records without confirming their purpose.
4. Wait for Cloudflare to complete certificate provisioning, then test HTTPS.
5. Use a dedicated subdomain when the root domain already hosts another site.

Follow Domains and DNS for the supported Worker-specific setup.

An unknown URL shows the home page instead of 404, or the 404 is missing

Symptoms: A bad URL does not serve the intended 404.html.

Fix: Keep src/pages/404.astro in the source and confirm pnpm build emits dist/404.html. On Cloudflare, also keep assets.not_found_handling set to 404-page in wrangler.jsonc. GitHub Pages, Vercel, and Netlify serve 404.html without a catch-all rewrite; remove SPA rewrites that turn unknown URLs into index.html.

GitHub Pages deploys but assets use the wrong path

Symptoms: The homepage opens at https://USERNAME.github.io/REPOSITORY/, but scripts, images, generated downloads, or a root-relative internal link return 404.

Fix: In Settings > Pages, set Build and deployment > Source to GitHub Actions, then inspect the Configure GitHub Pages and Build site workflow steps. The workflow must pass the action’s configured base_path to the build; do not add /REPOSITORY manually in astro.config.mjs or component URLs. Rebuild locally with STARRYBIO_BASE_PATH=/REPOSITORY and confirm dist/index.html contains /REPOSITORY/_astro/ and /REPOSITORY/assets/. See Deploying to GitHub Pages.

Vercel or Netlify uses the wrong build settings

Symptoms: The provider reports a missing output directory, runs npm instead of pnpm, uses an unsupported Node version, or serves an empty/old site.

Fix: Keep the repository root as the provider base/root directory. Vercel uses vercel.json; Netlify uses netlify.toml and .node-version. Confirm the build command is pnpm build, output/publish directory is dist, and Node is 24.x. The committed vercel.json overrides Vercel’s listed build fields, and netlify.toml takes precedence over matching Netlify dashboard values. Vercel also needs the non-secret build variable ENABLE_EXPERIMENTAL_COREPACK=1 so it can use the pinned pnpm 12 version; Netlify reads that version directly from packageManager. The stock project needs no application secrets. Redeploy after correcting the provider configuration.

An update or deployment made the site worse

Immediate response: Use Cloudflare’s Worker deployment history or the bundled CLI:

pnpm exec wrangler versions list
pnpm exec wrangler rollback

Then restore/fix the matching local source commit before deploying again. Operations and Updates describes the safe update and rollback workflow.

Still stuck

Collect the StarryBio version, Node/pnpm versions, exact command, sanitized error text, relevant configuration fragment with secrets removed, and the public URL only if you are comfortable sharing it. Check the project issue templates after reading this wiki. Report security vulnerabilities privately, as described in Security and Privacy.