thedotmack/claude-mem · error

Instruction not found

Error message

Instruction not found

What it means

When ?operation= passes the allow-list, the server serves content cached at boot from bundled instruction files. If the operation's file was absent at startup, cachedOperationContent has no entry and the route returns 404 'Instruction not found' — the parameter was valid but the artifact never loaded.

Source

Thrown at src/services/server/Server.ts:278

    });

    this.app.get('/api/instructions', (req: Request, res: Response) => {
      const topic = (req.query.topic as string) || 'all';
      const operation = req.query.operation as string | undefined;

      if (topic && !ALLOWED_TOPICS.includes(topic)) {
        return res.status(400).json({ error: 'Invalid topic' });
      }

      if (operation && !ALLOWED_OPERATIONS.includes(operation)) {
        return res.status(400).json({ error: 'Invalid operation' });
      }

      if (operation) {
        const cached = cachedOperationContent.get(operation);
        if (cached === undefined) {
          logger.debug('HTTP', 'Instruction file not cached at boot', { operation });
          return res.status(404).json({ error: 'Instruction not found' });
        }
        return res.json({ content: [{ type: 'text', text: cached }] });
      }

      if (cachedSkillMd === null) {
        logger.debug('HTTP', 'SKILL.md not cached at boot', { topic });
        return res.status(404).json({ error: 'Instruction not found' });
      }
      const sectionText = this.extractInstructionSection(cachedSkillMd, topic);
      res.json({ content: [{ type: 'text', text: sectionText }] });
    });

    this.app.post('/api/admin/restart', requireLocalhost, async (_req: Request, res: Response) => {
      const isWindowsManaged = process.platform === 'win32' &&
        process.env.CLAUDE_MEM_MANAGED === 'true' &&
        process.send;

      if (isWindowsManaged) {

View on GitHub (pinned to e2d1df569a)

Solutions

1. Reinstall or rebuild the package so all instruction files ship, then restart the worker (caching is boot-time)
2. Verify the operation's instruction file exists in the installed package's instructions directory
3. Check the server's debug log for 'Instruction file not cached at boot' with your operation name

async function getOperationInstructions(base: string, operation: string) {
  const res = await fetch(`${base}/api/instructions?operation=${encodeURIComponent(operation)}`);
  if (res.status === 404) return null; // file not cached at boot — packaging gap, not a bad name (that is 400)
  if (!res.ok) throw new Error(`instructions failed: ${res.status}`);
  return res.json();
}

function isInstructionMissing(status: number, body: unknown): body is { error: 'Instruction not found' } {
  return status === 404 && typeof body === 'object' && body !== null && (body as { error?: string }).error === 'Instruction not found';
}

const res = await fetch(`${base}/api/instructions?operation=${op}`);
const body = await res.json().catch(() => ({}));
if (isInstructionMissing(res.status, body)) {
  // valid name, missing artifact: rebuild/reinstall the package; meanwhile fall back to full SKILL.md
  return (await fetch(`${base}/api/instructions`).then(r => r.json()));
}

When it happens

Trigger: GET /api/instructions?operation=<allowed-name> on an install where that operation's instruction file was not bundled: excluded by packaging rules, renamed, or version skew between client expectations and shipped files.

Common situations: npm publish rules dropping markdown assets; partial or truncated installs; running from a stale build after the operation set changed; files added after the worker booted are invisible until restart.

Related errors

• session_not_found
• NotFound
• not_found
• NotFound
• ViewerUnavailable

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/6b4187a4da7cc2d1. Report an issue: GitHub.