Aakvatech Limited - SessionBootFailed After Migrating from Frappe v15 to v16

If you’ve recently migrated a Frappe/ERPNext instance from **version 15 to version 16** and suddenly encounter:

April 10, 2026 · 2 min read

frappe.exceptions.SessionBootFailed
...
orjson.JSONDecodeError: unexpected character

you’re not dealing with a generic boot failure — this is a data integrity issue in active sessions.

This issue is subtle, reproducible, and tied specifically to live sessions during migration. The fix is straightforward, but understanding why it happens helps prevent future disruptions.

Root Cause

During the upgrade from v15 → v16, Frappe introduced stricter JSON parsing using orjson.

At the same time:

Existing user sessions (tabSessions.sessiondata) created in v15
May contain non-strict JSON formats, partial writes, or legacy structures
Are still active during migration

After upgrade:

Frappe attempts to parse these session records during boot (active_sessions)
orjson enforces stricter parsing rules than older implementations
Any malformed session payload causes:

orjson.JSONDecodeError
→ SessionBootFailed

Key Insight

This only occurs if there were active sessions during migration.

If all users were logged out before upgrade, the issue typically does not appear.

Symptoms

Users cannot access Desk
Website routes may also fail

Error consistently appears during boot:

frappe.sessions.get() → get_bootinfo() → get_user() → active_sessions

Traceback points to:
```
frappe.parse_json(session.sessiondata)
```

The Fix (Required)

✅ Invalidate All Sessions

You must remove all existing session records.

The most reliable approach:

bench --site your-site mariadb

TRUNCATE TABLE `tabSessions`;

🔁 Then clear caches and restart:

bench --site your-site clear-cache
bench --site your-site clear-website-cache
bench restart

Why This Works

Removes all corrupted or incompatible sessiondata
Forces fresh session creation under v16 format
Prevents orjson from encountering invalid payloads

Alternative (Not Recommended)

DELETE FROM `tabSessions`;

Works similarly, but:

Slower on large tables
Does not reset table metadata

What Does NOT Work

Clearing Redis only
Expiring sessions via expiry field
Rebuilding permissions
Restarting services alone

These approaches do not remove corrupted sessiondata, which is the root issue.

Preventing This in Future Migrations

✅ Best Practice Before Upgrading

Before running bench migrate:

bench --site your-site mariadb

TRUNCATE TABLE `tabSessions`;

Or ensure:

All users are logged out
No active sessions exist

✅ Safer Upgrade Workflow

Put site in maintenance mode:

bench --site your-site set-maintenance-mode on

Clear sessions:
```
TRUNCATE TABLE tabSessions;
```
Run migration:
```
bench migrate
```
Restart:
```
bench restart
```

Disable maintenance mode:

bench --site your-site set-maintenance-mode off

Final Takeaway

This is not a bug in your application logic — it’s a migration edge case caused by stricter JSON parsing in v16 combined with legacy session data.

If you hit SessionBootFailed after upgrading from v15 to v16, deleting all sessions is not optional — it is required.

If It Happens Again

If the issue reappears after cleanup:

Investigate custom code writing to tabSessions
Ensure sessiondata is always valid JSON
Check for background jobs mutating sessions