Quick reference. Each row says what to check first and points to the full chapter.
On this page
Install
| Question | Fix |
|---|
/install/ 403 | The deny rule blocks the installer too; lock it only after setup (install) |
500 Unknown column 'c.words' | Legacy schema: ALTER TABLE ye_contents ADD COLUMN words INT UNSIGNED NOT NULL DEFAULT 0; then backfill |
| Posts 404, admin OK | Rewrite not active — apply the Nginx config and reload |
| Upload fails | uploads/ ownership/permissions (permissions) |
| DB connection fails | Test credentials with the mysql client, then check config.inc.php |
| Installed, now what? | Quick start |
Themes & home
| Question | Fix |
|---|
| Home unchanged after switching theme | Delete var/home-static/index.html (and /en/), flush page cache |
Template missing / blank home | Theme lacks views/layout.php; the core falls back to yecha and logs it |
| CSS edits not visible | Use View::asset() for ?v=<mtime> URLs, never a fixed query string |
| Dark mode unreadable | Add html.dark rules for panels/tables/code (themes) |
| Reorder sidebar blocks | Layouts in admin or theme.sidebar_mode (user guide) |
Admin
| Question | Fix |
|---|
| Login loops | Check fastcgi_param HTTPS on, site.url, hostname; clear cookies |
| 500 on saving | Enable DEBUG briefly, php -l changed files, confirm migrations ran |
| Form rejected | Writes need Csrf::field() + Csrf::check() |
| A module disappeared | notes / poly hide when disabled; check plugin.<id>.enabled for others |
| Admin password lost | tools/admin-pass.php or the Users module (back up first) |
Content & i18n
| Question | Fix |
|---|
| Post URL 404 | Slug colliding with Router::RESERVED, status not publish, or deleted_at set |
| Category count unchanged after deleting posts | ye_metas.count is precomputed — recalculate |
/en/xxx.html shows Chinese | Translation missing or not publish; base fallback is expected (i18n) |
| Link returns to Chinese | Missing language prefix; use ui_lp() / Poly::termUrl() |
| Category name Chinese on English page | Fill ye_metas.names_i18n (terms) |
| AI result is still Chinese | 1.2.3 validation blocks it and reports an error; edit manually and set manual_override |
/ja/theme 404 | Existing behaviour for plugin pages; only Chinese and /en are exposed (URL rules) |
| HTML in body shown as text | Body is escaped — no HTML in Markdown; use a theme view or core renderer (writing rules) |
Plugins & market
| Question | Fix |
|---|
| Enable fails | Check migration failure; migrations/ must be idempotent; the admin shows the error |
| Data gone after disabling | Disabling keeps data; only uninstall purge=1 removes tables/options |
| Market install fails | https + SHA-256 only; check package structure, plugin.php / theme.json, php -l |
| Custom route not firing | Use the pages manifest; there is no Hooks::run('route') dispatcher (hooks) |
/mall, /site, /ai 404 | Those branches fall back to 404 when the plugin is off |
Cache & upgrade
| Question | Fix |
|---|
| Front end unchanged after edit | Flush page cache, block cache, baked home (cache) |
| Changelog not updating | It is a DB content page; editing CHANGELOG.md alone does nothing — update both |
| 500 after upgrade | php tools/upgrade.php --component core --dry-run, or roll back |
| Theme/plugin count mismatch | Directories vs manifests; back up same-named themes before overwriting |
| New content lost after rollback | Restoring the DB overwrites later content — export it first |
SEO & URLs
| Question | Fix |
|---|
| Out-of-range page returns empty 200 | Current core returns 404; the rule lives in Router::pageBeyond() |
| Self-referencing canonical | Pager and total page count must share one source; never fold invalid pages into page 1 |
| Missing pages in sitemap | Pages need type='page', status='publish', deleted_at IS NULL |
/docs and /docs.html both work | Equivalent clean-URL special case; pick one externally |
| Wrong feed contents | Only published, non-deleted post rows; check published_at |
Performance
| Question | Fix |
|---|
| Home occasionally slow | Check stats.posts_total and whether Front::postsTotal() takes the O(1) path |
| Deep taxonomy pages 2–10s | Check ye_meta_page_bounds fast path; tw joined in 1.2.4 |
| List page full scan | EXPLAIN the ORDER BY; never return to live term-count subqueries |
| Overwrite translation slows the site | Since 1.2.2 it is one language per request + lock + auto-chain; suspect old code |
| Same slow-query fingerprint repeats | Follow instrument → measure → isolate → fix → re-measure (performance) |
Still stuck?
- Read
var/log/php-error.log, PHP-FPM slow log and MySQL slow log; get a concrete error/fingerprint first. - Post in the forum with version,
php -l result, reproduction URL and log snippets (never paste secrets). - For issues, follow
RELEASE.md: state root cause, criteria and verification so it can be reproduced.