Most problems on a Velk site come from a short list of causes, and the AI knows where to look: the server's error log, the .htaccess file (the server's address rules), the storage/ folder, the theme. Your part is the description. Below are the common symptoms, what usually causes each one and what to ask.
Describe it like this
Since I published the theme this morning, the Products page of the Trigo Bom site shows a white screen. The home opens. Read the server's error log and tell me the cause before changing anything.
Symptom, where, what changed last, and a request to diagnose first: that takes the AI straight to the right place.
A white screen, or a page that says only “500 Server Error”
A PHP error. On a live site APP_DEBUG (the setting that prints error details on screen) is off, as it should be, so the visitor sees nothing useful and the detail goes to the server's PHP error log. Ask the AI to read it.
After an update, one known cause is a theme function with the same name as one the engine now declares, such as richtext in v3.9.0. The upgrade notes catch it when you update by asking.
The home opens, inner pages give 404
Almost always the address rules: the .htaccess file didn't go up, or the server ignores it. bin/velk files:init recreates a missing .htaccess from Velk's template and never overwrites an existing one. On nginx (another kind of web server), the rules go in the server's configuration, from Velk's nginx.conf.example.
Two other causes: a list such as /blog exists only if a page lists the posts (Velk makes no automatic archive), and since v3.9.0 a template (the file that draws a kind of page) declared in site.json but missing from the theme gives a 404, which schema:validate lists under “Warnings:”.
Images missing
The storage/uploads/ folder didn't go up with the site, or the server can't write to it. An image shown at full size where a cropped one was expected means that size was never generated: bin/velk media:variants creates missing sizes, and --regen rebuilds them after a size changes in site.json. If sizes never appear, the server's PHP may lack its image extension (GD).
Broken images and links only on a site installed in a subfolder (example.com/new/) mean the theme writes addresses by hand instead of using Velk's helpers (the functions that build addresses).
“Atualizando…” or “Atualização falhou” after an update
After new engine files arrive, Velk applies the database adjustments (migrations) on the first visit. A plain page saying “Atualizando…” (Portuguese for “Updating…”) means they're running; it reloads itself in a few seconds. “Atualização falhou” (“Update failed”) means one failed, and the site stays on that page until it's fixed.
The reason is in storage/cache/migration-error.json and storage/logs/migration.log: ask the AI to read both. Once the cause is fixed, bin/velk migrate applies the rest and brings the site back. Migrations aren't all-or-nothing, so one that stopped halfway may need a manual fix in the database first.
A message box is blank
Since v3.7.1 the engine doesn't write the sentences visitors read. It returns a code (submitted, validation_failed…) and the theme turns each code into words, in theme/functions.php. A code the theme doesn't know shows as an empty box, or as the bare code: after an update that brought new codes, like the multi-step forms of v3.7.8, or on a new screen such as a login. The fix is one line per code; ask the AI to find the unmapped codes and write the sentences.
Form e-mails don't arrive
The lead is saved even when the e-mail fails, and the submission in the admin shows the e-mail status. The usual causes: no recipients on the form's screen in the admin, or wrong e-mail settings (SMTP_*) in the server's .env (the file with the site's passwords and keys). A test sent from a local copy never reaches the client, by design: the local copy doesn't get the form recipients.
A change doesn't show
- A color or layout change. Browsers keep CSS and JS files for a month, so the theme must load them with a version in the address. The publish warns when it's missing; ask the AI to add it.
- Content changed in a local copy stays on your computer: publishing sends the theme only. Change content on the live site, in its admin or by conversation.
- A CDN in front (a network that keeps copies of pages near visitors, such as Cloudflare): with
CACHE_TTLabove 0, public pages stay cached that long. Wait, or clear the CDN's cache. - Still a draft. Saved isn't published.
How to describe a problem
-
The symptom
What you see, in your words: a white screen, a 404, an empty box, a missing image.
-
Where
Which page, which language, phone or computer, logged in or not.
-
What changed last
An update, a theme publish, a new script, a move to another host.
-
Diagnosis first
Ask for the cause before the fix. For a bigger fix, ask for the plan and read it before the AI acts.
Questions
Can I turn on APP_DEBUG to see the error?
On your computer, yes. On the live site, no: it shows file paths, queries and versions to every visitor. Let the AI read the server's log instead.
It works on my computer but not on the server. Why?
Often the PHP version: code that runs on a newer PHP can be a fatal error on an older one. Ask the AI to compare the two; the PHP on your computer should match the server's.