Troubleshooting
The symptoms people actually report, what each one usually is, and the two screens that answer most questions.
Most problems with this installation are one of ten things. This page is ordered by how often each one turns up, and each row names where to look rather than what to think.
The table
| What you see | What it usually is |
|---|---|
| The app starts, and nothing loads | NEXT_PUBLIC_CONVEX_URL is missing or points at the wrong deployment |
| Sign in refuses, or sessions do not stick | BETTER_AUTH_SECRET is missing from the deployment, or the deployment is unreachable |
| A blank page for a few seconds after starting | Normal. Next.js serves nothing until the first compile finishes |
| A change in the panel does not appear on the site | Settings are cached briefly by design. Reload, then check the screen for a Save button |
| Confirmation and reset mails never arrive | RESEND_API_KEY or EMAIL_FROM, or a sending domain that is not verified |
| A feature is simply switched off | That is what leaving a name for later does. Turn it on in Platform → Environment |
| The social button says the provider is not configured | One of the two names for that provider is missing, or was set on the other deployment |
| The setup file will not open on macOS | The unidentified-developer dialog. Right-click, Open. Once per download |
| The installer says Node is missing or too old | Install the current LTS, and check that the terminal is using it |
| An answer arrives all at once, or stops midway | A reverse proxy that buffers or closes a streamed response |
The two screens that answer most questions
System → Status & health
Four checks, each with a time and each naming the variable it is missing. The app, the backend, the model gateway and the mail provider. If one is red, you are done looking: the row says what to fix.
System → Audit log
Who changed what, and when. It turns "it changed by itself" into a name and a timestamp, and it is the fastest way to find out what you did an hour ago.
Working through it properly
Deliberate behaviours that look like faults
| Behaviour | Why it is on purpose |
|---|---|
| A social button that says the provider is not configured | Better than a button that does nothing when pressed |
| An empty panel screen rather than an error | A partially configured installation stays navigable |
| Refusals counted separately from failures | They are different problems with different fixes |
| A settings change that takes a moment to appear | Caching, which is why the site is fast |
| No focus ring after a click | The house style: borders and backgrounds carry the affordance |
| Shared links that expose nothing but the item | Files shared one at a time, with no directory behind them |
| The password floor refusing a short password | It is a setting in System → Security, not a bug |
What to send yourself when you write to somebody about it
Four things, and they answer most questions before they are asked: the version from
System → Setup & licensing, the four rows from System → Status & health, the last few entries of
System → Audit log around the time it went wrong, and what the terminal said. Never a screenshot of the
Platform → Environment screen with values in it: that screen never shows values, and the habit is the point.