thedotmack/claude-mem · info

Onboarding explainer not available

Error message

Onboarding explainer not available

What it means

HTTP 404 from the onboarding-explainer endpoint. The markdown asset is read once at module load (SearchRoutes.ts:23) from ../skills/how-it-works/onboarding-explainer.md relative to the compiled file; if that read fails the cache is null and every request to the endpoint 404s for the process lifetime. It is a packaging/asset problem, not a runtime failure.

Source

Thrown at src/services/worker/http/routes/SearchRoutes.ts:442

    }

    res.json({ context: lines.join('\n'), count: observations.length });
  });

  private queryWithPlatformSource(req: Request): Record<string, any> {
    const platformSource = this.getOptionalPlatformSourceFromRequest(req);
    if (!platformSource) {
      return req.query as Record<string, any>;
    }
    return {
      ...(req.query as Record<string, any>),
      platformSource,
    };
  }

  private handleOnboardingExplainer = this.wrapHandler((_req: Request, res: Response): void => {
    if (cachedOnboardingExplainer === null) {
      res.status(404).json({ error: 'Onboarding explainer not available' });
      return;
    }
    res.setHeader('Content-Type', 'text/markdown; charset=utf-8');
    res.send(cachedOnboardingExplainer);
  });

  private handleGetTimelineByQuery = this.wrapHandler(async (req: Request, res: Response): Promise<void> => {
    const result = await this.searchManager.getTimelineByQuery(this.queryWithPlatformSource(req));
    res.json(result);
  });
}

View on GitHub (pinned to 8bc631a71a)

Solutions

1. Treat 404 as 'feature absent' and hide/disable the explainer UI section
2. If you package the worker yourself, ensure skills/how-it-works/onboarding-explainer.md is copied next to the compiled routes
3. Restarting alone will not help — the file must exist at boot; check the boot log line 'Onboarding explainer not present at boot'

Example fix

// before
const md = await (await fetch(`${base}/api/onboarding/explainer`)).text();
show(md); // renders raw 404 JSON

// after
const r = await fetch(`${base}/api/onboarding/explainer`);
if (r.ok) show(await r.text());
else hideExplainerSection(); // 404 means asset not bundled

const r = await fetch(`${base}/api/onboarding/explainer`);
const explainer = r.ok ? await r.text() : null; // null => feature not shipped

function explainerAvailable(res: Response): boolean {
  return res.ok && (res.headers.get('content-type') ?? '').includes('text/markdown');
}

When it happens

Trigger: GET the onboarding explainer route when the markdown file was not shipped in the build output — typically running from a source checkout or a package layout where the skills/ directory is excluded from the bundle.

Common situations: Custom builds that tree-shake non-code assets; running the worker from a repo clone without the full build-and-sync step; a plugin/UI that unconditionally renders the explainer on first run and shows an error tile instead of hiding itself.

Related errors

• session_not_found
• NotFound
• not_found
• NotFound
• NotFound

AI-assisted analysis of thedotmack/claude-mem@8bc631a71a (2026-08-20). Data as JSON: /api/errors/82cf26f1027e7806. Report an issue: GitHub.