Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix Bug: Isolated agentTurn cron jobs fail - docs/reference/templates not bundled in npm package [1 pull requests, 1 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#57945•Fetched 2026-04-08 01:55:54
View on GitHub
Comments
0
Participants
1
Timeline
2
Reactions
0
Author
jvpflumjvpflum
Participants
jvpflumjvpflum
Timeline (top)
cross-referenced ×1referenced ×1

All isolated agentTurn cron jobs fail at launch with the following error before any payload runs:

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

Error Message

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

Root Cause

The loadTemplate() function in workspace-CFIQ0-q3.js resolves a template directory at:

{packageRoot}/docs/reference/templates/

This directory is not included in the published npm package. The dist/ folder contains compiled JS bundles but no docs/ subdirectory, so any call to loadTemplate("AGENTS.md") throws immediately.

Fix Action

Fix

The docs/reference/templates/ directory and its template files must be included in the npm package. In package.json, ensure the files array (or build output) includes this path:

{
  "files": [
    "dist/**",
    "docs/reference/templates/**"
  ]
}

Alternatively, bundle the template content directly into the compiled JS so it does not depend on filesystem path resolution at runtime.

Workaround

Manually create the missing directory and placeholder files:

# Windows
New-Item -ItemType Directory -Force -Path "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates"
"# AGENTS.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\AGENTS.md"
"# BOOTSTRAP.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\BOOTSTRAP.md"

# macOS/Linux
mkdir -p "$(npm root -g)/openclaw/docs/reference/templates"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/AGENTS.md"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/BOOTSTRAP.md"

Note: This workaround is wiped on every npm install -g openclaw@latest.

PR fix notes

PR #57946: fix: use FALLBACK_TEMPLATE_DIR when no candidate path exists (fixes isolated agentTurn cron jobs)

Description (problem / solution / changelog)

Fix: Use FALLBACK_TEMPLATE_DIR when no candidate path exists

Closes #57945

Problem

resolveWorkspaceTemplateDir() iterates through candidate paths and falls through to:

cachedTemplateDir = candidates[0] ?? FALLBACK_TEMPLATE_DIR;

When no candidate path exists (the common case after npm install -g openclaw), this returns candidates[0] — the packageRoot-relative path — instead of FALLBACK_TEMPLATE_DIR.

candidates[0] is {packageRoot}/docs/reference/templates, which does not exist in the published npm package because the bundling process only outputs to dist/. This caused all isolated agentTurn cron jobs to fail at launch with:

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

Fix

Change the fallback from candidates[0] to FALLBACK_TEMPLATE_DIR:

// Before
cachedTemplateDir = candidates[0] ?? FALLBACK_TEMPLATE_DIR;

// After
cachedTemplateDir = FALLBACK_TEMPLATE_DIR;

FALLBACK_TEMPLATE_DIR is resolved relative to the source file using import.meta.url:

const FALLBACK_TEMPLATE_DIR = path.resolve(
  path.dirname(fileURLToPath(import.meta.url)),
  "../../docs/reference/templates",
);

When bundled, import.meta.url points to the compiled file in dist/, so this resolves to {packageRoot}/docs/reference/templates — which is the correct location and is included in the npm package via the "docs/" entry in package.json files.

Impact

  • Fixes critical regression where 20+ cron jobs fail simultaneously on fresh installs
  • No behavior change when the template dir is found via a candidate path
  • Single line change, minimal risk

Changed files

  • src/agents/workspace-templates.ts (modified, +1/-1)

Code Example

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

---

{packageRoot}/docs/reference/templates/

---

# Windows
New-Item -ItemType Directory -Force -Path "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates"
"# AGENTS.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\AGENTS.md"
"# BOOTSTRAP.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\BOOTSTRAP.md"

# macOS/Linux
mkdir -p "$(npm root -g)/openclaw/docs/reference/templates"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/AGENTS.md"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/BOOTSTRAP.md"

---

{
  "files": [
    "dist/**",
    "docs/reference/templates/**"
  ]
}
RAW_BUFFERClick to expand / collapse

Bug: Isolated agentTurn cron jobs fail with "Missing workspace template: AGENTS.md"

Version: 2026.3.28 (f9b1079) OS: Windows 11 (x64) Severity: Critical — blocks entire cron fleet

Summary

All isolated agentTurn cron jobs fail at launch with the following error before any payload runs:

Error: Missing workspace template: AGENTS.md (...\openclaw\dist\docs\reference\templates\AGENTS.md). Ensure docs/reference/templates are packaged.

Root Cause

The loadTemplate() function in workspace-CFIQ0-q3.js resolves a template directory at:

{packageRoot}/docs/reference/templates/

This directory is not included in the published npm package. The dist/ folder contains compiled JS bundles but no docs/ subdirectory, so any call to loadTemplate("AGENTS.md") throws immediately.

Impact

Every cron job using sessionTarget: "isolated" and payload.kind: "agentTurn" dies before executing. In a typical workspace this can affect 20+ scheduled jobs simultaneously, including:

  • Knowledge Base Growth
  • Nightly System Maintenance
  • Email Triage (Yahoo)
  • Hue Evening Wind Down
  • GitHub Daily Digest
  • Daily Blog Digest
  • Gateway Heartbeat Check
  • Bill Sweep, Bill Alert, Portfolio Monitor, and more

All show consecutiveErrors >= 2 within minutes of the issue appearing.

Workaround

Manually create the missing directory and placeholder files:

# Windows
New-Item -ItemType Directory -Force -Path "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates"
"# AGENTS.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\AGENTS.md"
"# BOOTSTRAP.md placeholder" | Out-File "$env:APPDATA\npm\node_modules\openclaw\docs\reference\templates\BOOTSTRAP.md"

# macOS/Linux
mkdir -p "$(npm root -g)/openclaw/docs/reference/templates"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/AGENTS.md"
echo "# placeholder" > "$(npm root -g)/openclaw/docs/reference/templates/BOOTSTRAP.md"

Note: This workaround is wiped on every npm install -g openclaw@latest.

Fix

The docs/reference/templates/ directory and its template files must be included in the npm package. In package.json, ensure the files array (or build output) includes this path:

{
  "files": [
    "dist/**",
    "docs/reference/templates/**"
  ]
}

Alternatively, bundle the template content directly into the compiled JS so it does not depend on filesystem path resolution at runtime.

Steps to Reproduce

  1. Install [email protected] via npm install -g openclaw
  2. Configure any cron job with sessionTarget: "isolated" and payload.kind: "agentTurn"
  3. Trigger the job
  4. Observe: job fails immediately with the "Missing workspace template" error

A PR with the fix is submitted alongside this issue.

extent analysis

Fix Plan

To resolve the issue, follow these steps:

  • Update the package.json file to include the docs/reference/templates/ directory in the files array:
{
  "files": [
    "dist/**",
    "docs/reference/templates/**"
  ]
}
  • Alternatively, bundle the template content directly into the compiled JS to avoid filesystem path resolution at runtime.

Code Changes

No code changes are required in the workspace-CFIQ0-q3.js file. The fix is solely in the package.json configuration.

Verification

After updating the package.json file, run the following commands:

npm install -g openclaw

Then, trigger a cron job with sessionTarget: "isolated" and payload.kind: "agentTurn". The job should now execute without errors.

Extra Tips

To avoid similar issues in the future, ensure that all required directories and files are included in the npm package. Regularly review the files array in package.json to guarantee that all necessary assets are bundled with the package.

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…
#search optimization#API routing#API middleware#SSR setup#ISR 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

openclaw - ✅(Solved) Fix Bug: Isolated agentTurn cron jobs fail - docs/reference/templates not bundled in npm package [1 pull requests, 1 participants]