intotheeast-com/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 /trips/<active_trip>/dailies 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 /var/www/html && 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']->deleteAll() (note: clear() does not exist on Grav\Common\Cache in Grav 1.7)
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 /trips/<active_trip>/dailies — 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 /var/www/html && 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

---

BUG-003 — One post per day limit; silent failure on duplicate date

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

Symptom

Submitting a second post with the same date as an existing entry shows "Entry posted successfully!" but creates no file. The user's post is silently discarded.

Root cause

The add-page-by-form plugin built the page slug from date only (Y-m-d), producing folder names like 2026-06-18.entry. With overwrite_mode: false, if that folder already exists the plugin skips page creation but does not abort — the message process step runs regardless, showing a false success.

Fix

Change the slug template in user/pages/02.post/post-form.md to include time and title:

{{ form.value.date|date('Y-m-d-Hi') }}-{{ form.value.title|lower|regex_replace('/[^a-z0-9]+/', '-')|trim('-') }}

Example: title "Arrived in Tokyo" at 14:30 on 2026-06-18 → 2026-06-18-1430-arrived-in-tokyo

The slug is locked at creation time. Renaming the title afterwards does not change the URL.

Acceptance criteria

1. Submit two posts on the same day with different times or titles — both appear in /trips/<active_trip>/dailies as separate entries
2. Renaming a post's title in the frontmatter does not break its URL

---

BUG-004 — Admin2 shows empty dashboard after Grav 2.0 upgrade

Status: fixed 2026-06-19

Symptom

After installing Grav 2.0 + Admin2, logging in shows an empty dashboard with no sidebar navigation (only a Settings item visible). Pages and content are not accessible.

Root causes (three separate issues)

A) Wrong user account type. system.yaml had accounts.type: regular (old file-based system). Admin2's API plugin uses the Flex user collection to look up accounts. With regular, the API saw zero users and entered setup-wizard mode.

B) Wrong pages type. system.yaml had pages.type: regular. Admin2's pages API requires pages.type: flex to serve the page tree.

C) Missing api.* permissions on user account. Grav 2.0 Admin2 uses a new api.* permission namespace (api.super, api.access, etc.) instead of the old admin.super. A user with only access.admin.super: true appears as a non-admin to Admin2.

Fix

In user/config/system.yaml:

accounts:
  type: flex
pages:
  type: flex

In user/accounts/<username>.yaml:

access:
  admin:
    login: true
    super: true      # keep for backward compat
  api:
    super: true      # required by Admin2
    access: true     # required by Admin2

Notes

• api.super: true causes Admin2 to grant all sub-permissions automatically (api.pages, api.config, etc.)
• JWT secret in user/plugins/api/api.yaml can stay empty — HMAC-SHA256 works with an empty key locally; production generates its own secure secret
• The old admin plugin must be disabled (enabled: false) to avoid route conflict with admin2

---

BUG-005 — PHP session fails after Grav 2.0 container upgrade

Status: fixed 2026-06-19

Symptom

After replacing Grav core files inside the container, all pages return a CRITICAL error in logs/grav.log: Failed to start session: session_start(): Failed to read session data: files (path: ). Site is inaccessible.

Root cause

The getgrav/grav Docker image's PHP configuration does not set session.save_path. Grav 1.7 worked because the image's default PHP config included it; the updated image layer did not.

Fix

Add to php/php-local.ini:

session.save_path = /tmp

Restart the container to pick up the change. This file is bind-mounted into the container so no image rebuild is needed.

---