#Config Validation Errors

#Overview

This guide covers configuration validation errors in OpenClaw, based on src/config/validation.ts. Config validation happens at startup and prevents OpenClaw from running if critical issues are detected. Understanding validation errors is essential for debugging startup failures.

#Symptoms

#Startup Failure

• OpenClaw exits immediately after launch
• No server initialization
• Error message before any other output

#Zod Schema Validation Errors

• Detailed validation error with JSON path
• Type mismatch errors (e.g., "expected string, got number")
• Missing required field errors

#Plugin Config Errors

• Message: "invalid config" for specific plugin
• Plugin config doesn't match declared schema
• Message: "plugin schema missing"

#Duplicate Agent Directory

• Message: "Duplicate agent directory detected"
• Multiple agents configured with same directory path
• Validation failure lists all duplicates

#Legacy Config Warning

• Warning about deprecated config format
• Suggestion to migrate to new format
• May or may not block startup

#Root Causes

#1. Schema Validation Failure (Lines 98-107)

Top-level OpenClaw config doesn't match schema:

const result = OpenClawSchema.safeParse(config);
if (!result.success) {
  throw new Error(`Config validation failed: ${formatZodError(result.error)}`);
}

Common issues:

• Wrong data type for field (string vs number)
• Missing required fields
• Unknown fields not in schema
• Invalid enum values

Detection: Zod schema validation at startup Recovery: Must fix config file, no automatic recovery

#2. Plugin Config Schema Mismatch (Lines 403-422)

Plugin config doesn't match plugin's declared configSchema:

const pluginSchema = plugin.configSchema;
if (pluginSchema) {
  const validation = pluginSchema.safeParse(pluginConfig);
  if (!validation.success) {
    errors.push({
      plugin: pluginName,
      error: formatZodError(validation.error)
    });
  }
}

Common causes:

• Plugin updated with new config requirements
• Typo in plugin config field name
• Missing required plugin-specific fields
• Plugin configSchema not defined in openclaw.plugin.json

Detection: Per-plugin schema validation Recovery: Fix plugin config section in openclaw.json

#3. Duplicate Agent Directories (Lines 108-118)

Multiple agents configured with same directory:

function findDuplicateAgentDirs(agents: AgentConfig[]): string[] {
  const dirs = agents.map(a => a.directory);
  const seen = new Set<string>();
  const duplicates = new Set<string>();

  for (const dir of dirs) {
    if (seen.has(dir)) {
      duplicates.add(dir);
    }
    seen.add(dir);
  }

  return Array.from(duplicates);
}

Common causes:

• Copy-paste error in agent configuration
• Same agent listed multiple times
• Symbolic link creating duplicate path

Detection: Directory path comparison Recovery: Remove duplicate entries from agents.list

#4. Plugin Diagnostic Errors (Lines 222-229)

Plugin-reported diagnostic errors during validation:

Plugin diagnostics can report:

• Missing dependencies
• Invalid file paths
• Incompatible versions
• Resource unavailability

Severity levels:

• Error: Blocks startup
• Warning: Logged but doesn't block
• Info: Informational only

Recovery: Depends on specific diagnostic, see plugin documentation

#5. Legacy Config Format (Lines 88-96)

Old config format detected:

function detectLegacyConfig(config: unknown): boolean {
  // Check for deprecated field names or structures
  return hasLegacyFields(config);
}

Common patterns:

• Old field names (e.g., llmProvider vs llm.provider)
• Deprecated nesting structure
• Removed configuration options

Recovery: Migrate to new config format, warnings include migration hints

#Diagnosis Flow