intotheeast-com-content/docs/bugs-and-fixes.md

Bugs & Fixes

Backlog of confirmed bugs with root cause analysis and implementation spec for the fix.

---

BUG-001 — New entry not visible after form submission

Status: fixed 2026-06-18
Reported: 2026-06-18

Symptom

After submitting a new post via /post, the entry page file is created correctly on disk but does not appear in the /tracker feed or in the Grav Admin panel until the cache is manually flushed.

Root cause

Grav's page-tree cache (cache/doctrine/) is not invalidated when add-page-by-form writes a new page to disk. The tracker template uses page.children, which Grav serves from cache — so the new child page is invisible until the cache is cleared.

Workaround (manual)

Run in terminal after each submission:

docker exec intotheeast_grav bash -c "cd /app/www/public && php bin/grav clearcache"

Fix spec

Wire cache-clear into the form process so it happens automatically on every successful submission.

Approach — custom Grav plugin event hook:

1. Create a small plugin user/plugins/cache-on-save/ with one event listener:
   • Listen on onFormProcessed
   • When the form name is new-entry, call $this->grav['cache']->clear()
2. Enable the plugin in user/config/plugins/cache-on-save.yaml

This is the cleanest approach: it fires exactly once per successful submission, requires no changes to post-form.md, and works for any future forms too.

Alternative — disable page cache entirely:

Set cache: { enabled: false } in system.yaml. Simpler but degrades frontend performance; not recommended for production.

Files to create/modify

File	Change
user/plugins/cache-on-save/cache-on-save.php	New plugin, ~30 lines
user/plugins/cache-on-save/cache-on-save.yaml	Plugin manifest, enabled: true
user/config/plugins/cache-on-save.yaml	Runtime config, enabled: true

Acceptance criteria

1. Submit a new post via /post
2. Navigate to /tracker — the new entry is visible immediately, no manual cache flush needed
3. Grav Admin also shows the new page immediately

---

BUG-002 — Stale Twig cache after theme file changes

Status: fixed 2026-06-18
Reported: 2026-06-18

Symptom

After theme template files are added or modified (e.g., creating partials/base.html.twig), Grav's Twig compiled-template cache still holds the old compiled version. Pages that extend the changed file throw 500 errors like "Template partials/base.html.twig is not defined" even though the file exists on disk.

Root cause

Grav caches compiled Twig templates in cache/twig/. When a new file is added, existing templates that reference it don't know to recompile — their cache entries are still valid from their own mtime perspective.

Workaround (manual)

Run after any theme file is added or changed:

docker exec intotheeast_grav bash -c "cd /app/www/public && php bin/grav clearcache"

Fix spec

Disable Twig template caching in development via user/config/system.yaml:

twig:
  cache: false

Acceptable for a single-user dev setup — eliminates both BUG-001's side-effect and this bug entirely. Performance cost is negligible at one-user scale. On production, leave Twig cache enabled (it's fine there because template files don't change at runtime).

Files to change:

File	Change
user/config/system.yaml	Add twig: { cache: false } under development section

Acceptance criteria

1. Add a new theme template file
2. Reload any page — no 500 error, template works immediately without manual cache flush

---