What causes "Failed to load configuration schema: ${errMsg}" in KeygraphHQ/shannon?

Verify the schema file exists and parses: `node -e "JSON.parse(require('fs').readFileSync('apps/worker/configs/config-schema.json','utf8'))"`.

KeygraphHQ/shannon · critical · PentestError

Failed to load configuration schema: ${errMsg}

Error message

Failed to load configuration schema: ${errMsg}

What it means

Module-load-time failure while reading or compiling the JSON Schema (config-schema.json) that backs all config validation. This is a packaging/fixture fault, not a user-config problem: the schema file is missing, unreadable, or is invalid JSON / an invalid JSON Schema that ajv.compile rejects. Because it runs at import time, it crashes the worker before any scan starts.

Source

Thrown at apps/worker/src/config-parser.ts:39

// Handle ESM/CJS interop for ajv-formats using require
const require = createRequire(import.meta.url);
const addFormats: FormatsPlugin = require('ajv-formats');

const ajv = new Ajv({ allErrors: true, verbose: true });
addFormats(ajv);

let configSchema: object;
let validateSchema: ValidateFunction;

try {
  const schemaPath = new URL('../configs/config-schema.json', import.meta.url);
  const schemaContent = await fs.readFile(schemaPath, 'utf8');
  configSchema = JSON.parse(schemaContent) as object;
  validateSchema = ajv.compile(configSchema);
} catch (error) {
  const errMsg = error instanceof Error ? error.message : String(error);
  throw new PentestError(`Failed to load configuration schema: ${errMsg}`, 'config', false, {
    schemaPath: '../configs/config-schema.json',
    originalError: errMsg,
  });
}

const DANGEROUS_PATTERNS: RegExp[] = [
  /\.\.\//, // Path traversal
  /[<>]/, // HTML/XML injection
  /javascript:/i, // JavaScript URLs
  /data:/i, // Data URLs
  /file:/i, // File URLs
];

/**
 * Format a single AJV error into a human-readable message.
 * Translates AJV error keywords into plain English descriptions.
 */
function formatAjvError(error: ErrorObject): string {

View on GitHub (pinned to 1ae0a142f8)

Solutions

Verify the schema file exists and parses: `node -e "JSON.parse(require('fs').readFileSync('apps/worker/configs/config-schema.json','utf8'))"`.
Rebuild the worker package (`pnpm run build`) so configs/ is restored.
Re-run `pnpm install` if the configs directory is missing or the checkout is incomplete.
Check file permissions on apps/worker/configs/config-schema.json.

Defensive patterns

Strategy: try-catch

Validate before calling

import { readFileSync } from 'node:fs';
try {
  JSON.parse(readFileSync('apps/worker/configs/config-schema.json', 'utf8'));
} catch (error) {
  console.error('config-schema.json is missing or invalid JSON:', (error as Error).message);
  process.exit(1);
}

Try / catch

// The throw happens at module load; guard with a dynamic import in a harness.
try {
  await import('./config-parser.js');
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Failed to load configuration schema')) {
    console.error('Schema fixture missing/corrupt. Rebuild the worker package.');
    process.exit(1);
  }
  throw error;
}

Prevention

Never hand-edit config-schema.json without re-running `pnpm run build`.
Treat a missing/corrupt configs/ dir as a build break — restore from git before importing.

When it happens

Trigger: apps/worker/configs/config-schema.json is absent, truncated, or contains invalid JSON; ajv.compile throws on a malformed schema; the file is unreadable due to permissions. Triggered the moment config-parser.ts is imported.

Common situations: A broken build that did not copy configs/ into dist; hand-editing the schema to invalid JSON; a pnpm install that left the configs dir empty; a corrupt checkout.

Related errors

AI-assisted analysis of KeygraphHQ/shannon@1ae0a142f8 (2026-08-12). Data as JSON: /api/errors/0134f21dfb81c0a0. Report an issue: GitHub.