FAQ

Quick reference. Each row says what to check first and points to the full chapter.

On this page

Install

QuestionFix
/install/ 403The 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 OKRewrite not active — apply the Nginx config and reload
Upload failsuploads/ ownership/permissions (permissions)
DB connection failsTest credentials with the mysql client, then check config.inc.php
Installed, now what?Quick start

Themes & home

QuestionFix
Home unchanged after switching themeDelete var/home-static/index.html (and /en/), flush page cache
Template missing / blank homeTheme lacks views/layout.php; the core falls back to yecha and logs it
CSS edits not visibleUse View::asset() for ?v=<mtime> URLs, never a fixed query string
Dark mode unreadableAdd html.dark rules for panels/tables/code (themes)
Reorder sidebar blocksLayouts in admin or theme.sidebar_mode (user guide)

Admin

QuestionFix
Login loopsCheck fastcgi_param HTTPS on, site.url, hostname; clear cookies
500 on savingEnable DEBUG briefly, php -l changed files, confirm migrations ran
Form rejectedWrites need Csrf::field() + Csrf::check()
A module disappearednotes / poly hide when disabled; check plugin.<id>.enabled for others
Admin password losttools/admin-pass.php or the Users module (back up first)

Content & i18n

QuestionFix
Post URL 404Slug colliding with Router::RESERVED, status not publish, or deleted_at set
Category count unchanged after deleting postsye_metas.count is precomputed — recalculate
/en/xxx.html shows ChineseTranslation missing or not publish; base fallback is expected (i18n)
Link returns to ChineseMissing language prefix; use ui_lp() / Poly::termUrl()
Category name Chinese on English pageFill ye_metas.names_i18n (terms)
AI result is still Chinese1.2.3 validation blocks it and reports an error; edit manually and set manual_override
/ja/theme 404Existing behaviour for plugin pages; only Chinese and /en are exposed (URL rules)
HTML in body shown as textBody is escaped — no HTML in Markdown; use a theme view or core renderer (writing rules)

Plugins & market

QuestionFix
Enable failsCheck migration failure; migrations/ must be idempotent; the admin shows the error
Data gone after disablingDisabling keeps data; only uninstall purge=1 removes tables/options
Market install failshttps + SHA-256 only; check package structure, plugin.php / theme.json, php -l
Custom route not firingUse the pages manifest; there is no Hooks::run('route') dispatcher (hooks)
/mall, /site, /ai 404Those branches fall back to 404 when the plugin is off

Cache & upgrade

QuestionFix
Front end unchanged after editFlush page cache, block cache, baked home (cache)
Changelog not updatingIt is a DB content page; editing CHANGELOG.md alone does nothing — update both
500 after upgradephp tools/upgrade.php --component core --dry-run, or roll back
Theme/plugin count mismatchDirectories vs manifests; back up same-named themes before overwriting
New content lost after rollbackRestoring the DB overwrites later content — export it first

SEO & URLs

QuestionFix
Out-of-range page returns empty 200Current core returns 404; the rule lives in Router::pageBeyond()
Self-referencing canonicalPager and total page count must share one source; never fold invalid pages into page 1
Missing pages in sitemapPages need type='page', status='publish', deleted_at IS NULL
/docs and /docs.html both workEquivalent clean-URL special case; pick one externally
Wrong feed contentsOnly published, non-deleted post rows; check published_at

Performance

QuestionFix
Home occasionally slowCheck stats.posts_total and whether Front::postsTotal() takes the O(1) path
Deep taxonomy pages 2–10sCheck ye_meta_page_bounds fast path; tw joined in 1.2.4
List page full scanEXPLAIN the ORDER BY; never return to live term-count subqueries
Overwrite translation slows the siteSince 1.2.2 it is one language per request + lock + auto-chain; suspect old code
Same slow-query fingerprint repeatsFollow instrument → measure → isolate → fix → re-measure (performance)

Still stuck?

  1. Read var/log/php-error.log, PHP-FPM slow log and MySQL slow log; get a concrete error/fingerprint first.
  2. Post in the forum with version, php -l result, reproduction URL and log snippets (never paste secrets).
  3. For issues, follow RELEASE.md: state root cause, criteria and verification so it can be reproduced.