Troubleshooting

Troubleshooting

Symptom	Likely cause	Fix
HTTP 500 "requires PHP >= 8.5.0"	older PHP	upgrade to 8.5; do not lower the gate
HTTP 500 "requires the PHP extension 'X'"	extension missing	enable it in php.ini or the FPM pool
HTTP 500 "vendor/autoload.php is missing"	bare clone without dependencies	composer install --no-dev --optimize-autoloader, or use the release archive
"Something went wrong" page	unhandled error	read storage/logs/app-YYYY-MM-DD.log; APP_DEBUG = true only temporarily, never public
Styles or icons 404	not reached through an entry script, or docroot mismatch	browse /index.php; keep SCRIPT_NAME intact behind a proxy; layout B needs the root .htaccess
.md.ini downloadable	server ignores .htaccess	switch to layout A (docroot public/) immediately
"Too many attempts" or setup loops	per-IP rate limit (default 10 per 15 min) or the setup code	wait the window out, or read storage/logs/setup.log (0600)
Actions return 403 csrf	stale tab	reload the page to fetch a fresh token
Upload 413	MAX_UPLOAD_MB or PHP upload_max_filesize / post_max_size	raise both; SVG uploads are refused by design
"Integrity check failed for X"	archive does not match its manifest	refused by design — retry or install manually
Styles wrong after a code change	OPcache with validate_timestamps = 0	reload PHP-FPM
updater.php returns 404	docroot is public/	3.4.1 ships public/updater.php; on an older tree copy it or use the admin panel
Manifest served as application/octet-stream	.webmanifest missing from mime.types	types { application/manifest+json webmanifest; } (nginx) or AddType application/manifest+json .webmanifest (Apache)
Anchor links to non-Latin headings do nothing	a build before 3.3.0 dropped non-ASCII ids in the sanitiser	upgrade; ids are [\p{L}\p{N}][\p{L}\p{N}_:.\-]{0,96}
tag: search returns nothing	the document has no frontmatter tags, or the index predates the tag	check ?api=search filters echo; rebuild the index
Update "succeeds" but nothing changes	you are already on that release — the dry run reports unchanged per file	read unchanged and verified in the dry-run answer
Setup page loops after a restore	.md.ini restored from an older snapshot without a password hash	set a password again, or restore the current .md.ini

Reading the logs

• storage/logs/app-YYYY-MM-DD.log — application log, one JSON object per line.
• storage/logs/audit-YYYY-MM-DD.log — who changed what: content writes, settings, key rotation, cache clears, updates.
• storage/logs/setup.log — the one-time first-run code, mode 0600.

When reporting a problem

Include the version (src/Core/Version.php), the PHP version, the web server, the layout (A/B/C) and the relevant log lines with the content redacted.