#handler failed: Error: Session file path must be within sessions directory

1 messages · Page 1 of 1 (latest)

uncut spruce
#

I have moved Openclaw to a different direction from .openclaw folder, since I want to have multiple openclaw bots.
Then I found this error.
Any insights for the cause? Thanks!

livid scaffoldBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

lusty ploverBOT
#

That error is coming from the session store path safety check.

When OpenClaw handles an incoming Discord message, it loads/updates the current session transcript under:

$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/

If your sessions.json contains a sessionFile that is absolute (or otherwise resolves outside that sessions/ directory), OpenClaw throws:

Session file path must be within sessions directory

This commonly happens after moving/renaming ~/.openclaw (or trying to share/copy it between multiple instances), because older runs could end up writing absolute paths into sessions.json, and after the move those paths point “outside” the new sessions dir.

Recommended way to run multiple bots (don’t manually move ~/.openclaw)

Use profiles, which isolate config + state dir + service names cleanly:

#

Example:

openclaw --profile bot1 onboard
openclaw --profile bot1 gateway --port 18789

openclaw --profile bot2 onboard
openclaw --profile bot2 gateway --port 19001

Quick fix to unblock your current instance

  1. Back up your state dir (the folder you moved to / are using as $OPENCLAW_STATE_DIR).
  2. Fix the session store:
  • Open: $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json
  • Look for entries like "sessionFile": "/old/path/.../.openclaw/.../sessions/<id>.jsonl"
  • Either:
#
  • remove the sessionFile fields (let OpenClaw regenerate defaults), or
    • change them to be relative (e.g. just <id>.jsonl)

Fastest “reset sessions” option (loses conversation history metadata; transcripts may still exist): rename sessions.json out of the way and restart the gateway.

Two things I need from you to be precise

  • openclaw --version
  • Did you set OPENCLAW_STATE_DIR / use --profile, or did you just move the folder on disk?

(If you paste openclaw status --all too, it’s usually enough to spot exactly which path it’s trying to use.)

unreal token
lusty ploverBOT
#

Hey! All good.

Are you hitting the same Session file path must be within sessions directory error, or just saying hi?

If it’s the error, paste:

  • openclaw --version
  • the first ~30 lines around the failure from openclaw logs --follow (or a screenshot)
  • and whether you moved ~/.openclaw manually vs using openclaw --profile <name>
uncut spruce
#

what is in sessions.json?

lusty ploverBOT
#

sessions.json is OpenClaw’s session index / metadata store.

  • Where it lives (default):
    $OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json
    (so usually ~/.openclaw/agents/default/sessions/sessions.json, and with profiles something like ~/.openclaw-<profile>/...)

  • What’s inside: a plain JSON object mapping a session key → a SessionEntry (metadata).
    It stores things like:

    • sessionId (uuid)
    • updatedAt (timestamp)
    • optional sessionFile (the transcript filename/path)
    • routing/delivery context (lastChannel, lastTo, lastThreadId, etc.)
    • some per-session overrides (model override, queue mode, etc.)

Example (simplified):

# 
{
  "discord:channel:1473...:thread:...:from:123...": {
    "sessionId": "2f4c7b3c-....",
    "updatedAt": 1739730000000,
    "sessionFile": "2f4c7b3c-....jsonl",
    "lastChannel": "discord",
    "lastTo": "1473...",
    "lastThreadId": "..."
  }
}
  • What it is NOT: the actual chat transcript.
    The transcript lives as .jsonl files next to it in the same folder.

Why it matters for your error