Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix Session Lifecycle: Trajectory File Orphaned After Shutdown Crash, Blocks Gateway Restart [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#75571•Fetched 2026-05-02 05:33:04
View on GitHub
Comments
1
Participants
2
Timeline
2
Reactions
2
Author
chrismclarnon-epchrismclarnon-ep
Participants
chrismclarnon-epchrismclarnon-epclawsweeper[bot]clawsweeper[bot]
Timeline (top)
closed ×1commented ×1

Gateway exits with FAILURE status during shutdown, leaving the current session's trajectory.jsonl file orphaned (referenced in sessions.json but missing on disk). On restart, the orphaned reference blocks session restoration, causing a deadlock in the session loader that manifests as a dual IPv6/IPv4 binding race condition and false "port already in use" error.

Impact: Every gateway stop → gateway start cycle risks orphaning the current session. On reboot after crash, orphan blocks startup until openclaw doctor --fix is run to archive the orphaned file.

Error Message

Gateway exits with FAILURE status during shutdown, leaving the current session's trajectory.jsonl file orphaned (referenced in sessions.json but missing on disk). On restart, the orphaned reference blocks session restoration, causing a deadlock in the session loader that manifests as a dual IPv6/IPv4 binding race condition and false "port already in use" error.

Root Cause

Session cleanup during shutdown is not transactional:

  • Trajectory.jsonl file deleted during shutdown crash
  • sessions.json NOT updated to remove reference
  • systemd auto-restart before recovery completes
  • Session loader tries to restore missing file → deadlock
  • Dual IPv6/IPv4 binding attempt hangs waiting for session restoration

Fix Action

Workaround

openclaw doctor --fix    # Archives orphaned trajectory files
openclaw gateway start   # Succeeds after orphans removed

Code Example

May 01 09:31:17 srv1531451 systemd[861]: Stopping openclaw-gateway.service - OpenClaw Gateway (v2026.4.26)...
May 01 09:31:17 srv1531451 systemd[861]: openclaw-gateway.service: Main process exited, code=exited, status=1/FAILURE
May 01 09:31:17 srv1531451 systemd[861]: Stopped openclaw-gateway.service - OpenClaw Gateway (v2026.4.26).

---

openclaw doctor --fix    # Archives orphaned trajectory files
openclaw gateway start   # Succeeds after orphans removed
RAW_BUFFERClick to expand / collapse

Summary

Gateway exits with FAILURE status during shutdown, leaving the current session's trajectory.jsonl file orphaned (referenced in sessions.json but missing on disk). On restart, the orphaned reference blocks session restoration, causing a deadlock in the session loader that manifests as a dual IPv6/IPv4 binding race condition and false "port already in use" error.

Impact: Every gateway stop → gateway start cycle risks orphaning the current session. On reboot after crash, orphan blocks startup until openclaw doctor --fix is run to archive the orphaned file.

Reproduction Steps

  1. Run gateway normally with active sessions
  2. Run openclaw gateway stop
  3. Check systemd logs: gateway exits with status=1/FAILURE instead of status=0
  4. Run openclaw gateway start
  5. Gateway startup hangs; probe times out; report "Port 18789 already in use" (misleading)
  6. Run openclaw doctor --fix → archives orphan → gateway recovers

Root Cause

Session cleanup during shutdown is not transactional:

  • Trajectory.jsonl file deleted during shutdown crash
  • sessions.json NOT updated to remove reference
  • systemd auto-restart before recovery completes
  • Session loader tries to restore missing file → deadlock
  • Dual IPv6/IPv4 binding attempt hangs waiting for session restoration

Systemd Journal Evidence

May 01 09:31:17 srv1531451 systemd[861]: Stopping openclaw-gateway.service - OpenClaw Gateway (v2026.4.26)...
May 01 09:31:17 srv1531451 systemd[861]: openclaw-gateway.service: Main process exited, code=exited, status=1/FAILURE
May 01 09:31:17 srv1531451 systemd[861]: Stopped openclaw-gateway.service - OpenClaw Gateway (v2026.4.26).

Last normal log entry: 2026-05-01T08:56:32.098+00:00 sessions.list 386ms

No shutdown cleanup logs before FAILURE exit.

Orphaned File Details

  • Session ID: 2ae14c76-e358-471f-af4d-3c561b15b545
  • Trajectory file: missing from disk after crash
  • Sessions.json reference: still present, pointing to missing file
  • File size when active: 284 KB
  • Last write before crash: 08:48:11 UTC
  • Doctor diagnosis: Found orphan; after archiving it, gateway startup succeeded

Expected Behavior

Clean shutdown should either:

  1. Atomically finalize session state (sync trajectory.jsonl + update sessions.json simultaneously), OR
  2. If crash occurs mid-shutdown, next startup should detect and repair inconsistencies

Workaround

openclaw doctor --fix    # Archives orphaned trajectory files
openclaw gateway start   # Succeeds after orphans removed

System Details

  • OpenClaw version: 2026.4.26 (be8c246)
  • Node: v22.22.2
  • OS: Linux (Ubuntu, VPS)
  • Gateway bind: loopback (127.0.0.1:18789)

Frequency

Observed on 2026-05-01 after two reboots (first cycle: 18 orphaned files, second: 1 orphaned file). Suggests this triggers on every shutdown that crashes or fails to complete cleanly.

extent analysis

TL;DR

The most likely fix is to ensure a clean shutdown of the gateway service, which can be achieved by running openclaw doctor --fix to archive orphaned trajectory files before restarting the gateway.

Guidance

  • Verify that the openclaw doctor --fix command is executed after a crash or unclean shutdown to remove orphaned references and prevent deadlocks.
  • Check the systemd logs for status=1/FAILURE to identify instances where the gateway exited abnormally, indicating a potential orphaned file.
  • Consider implementing a transactional session cleanup during shutdown to prevent orphaned files, ensuring that either the session state is finalized atomically or inconsistencies are detected and repaired on startup.
  • Run openclaw gateway start after archiving orphaned files to ensure a successful startup.

Example

openclaw doctor --fix
openclaw gateway start

Notes

The provided workaround using openclaw doctor --fix is effective in resolving the issue but may not address the underlying cause of the crash or unclean shutdown. Further investigation into the root cause of the shutdown failure may be necessary to prevent future occurrences.

Recommendation

Apply the workaround by running openclaw doctor --fix before restarting the gateway, as it provides a reliable method to archive orphaned trajectory files and prevent deadlocks, allowing for a successful startup.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#network issue#logging issue#authentication issue#prompt issue#agent setup

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING