Skip to content

Error Codes Reference

Karandash uses exit codes to communicate results to CI/CD pipelines and scripts. Every exit code maps to a specific category of outcome.

Exit Codes

Code Constant Description
0 SUCCESS Validation passed. All rules satisfied.
1 VALIDATION_FAILED One or more validation rules failed.
2 CONFIG_ERROR Configuration file is missing, malformed, or contains invalid options.
3 PROVIDER_ERROR Failed to connect to or authenticate with the platform provider (GitLab, GitHub, etc.).
4 INTERNAL_ERROR Unexpected internal error (bug or unhandled exception).
5 VALIDATION_WARNING Validation passed but warnings exist. Only returned when --strict flag is used.
6 EXECUTION_ERROR Plugin signing, compilation, or execution error.
7 GLOBAL_TIMEOUT The global watchdog timeout was exceeded before the run finished.

Exit Code Details

Exit Code 0 -- Success

All configured validation rules passed. The MR meets all requirements.

karandash validate --mr-id 123 --platform github --project owner/repo
echo $?  # 0

Exit Code 1 -- Validation Failed

One or more rules produced ERROR-severity findings. The MR does not meet the configured requirements.

Common causes: - Title does not match required pattern - Missing required labels - Insufficient approvals - Branch naming convention violated - Secret detected in diff

CI/CD usage:

# GitLab CI
validate:mr:
  script:
    - karandash validate
  allow_failure: false  # Pipeline fails on exit code 1

Exit Code 2 -- Configuration Error

The configuration file cannot be parsed or contains invalid values.

Error catalog code: E0005

Common causes: - Syntax error in .karandash/config.kts or YAML file - Missing required field (e.g., pattern in titleFormat) - Invalid option combination (e.g., --watch and --fix together) - Missing required CLI flags for live mode - Config file not found when --watch mode is requested

Troubleshooting:

# Verify configuration
karandash doctor

# Validate config without running rules
karandash validate --dry-run

Exit Code 3 -- Provider Error

Failed to communicate with the platform API.

Error catalog code: E0100

Common causes: - Authentication token expired or invalid - Network connectivity issues - API rate limiting - Wrong platform URL - MR/PR not found (wrong project ID or MR ID) - Provider does not support mutation (when using --fix)

Troubleshooting:

# Check auth configuration
karandash doctor

# Verify token is set
echo $GITHUB_TOKEN | head -c 10

Exit Code 4 -- Internal Error

An unexpected error occurred inside Karandash. This typically indicates a bug.

Common causes: - Unhandled exception in validation engine - Plugin crash during execution - Serialization failure when parsing MR data

If you encounter this exit code consistently, consider filing a bug report.

Exit Code 5 -- Validation Warning (Strict Mode)

Validation passed but WARNING-severity findings exist. This exit code is only returned when the --strict flag is active.

Without --strict, warnings do not affect the exit code (the process exits with 0).

# Warnings cause exit code 5
karandash validate --strict
echo $?  # 5 if warnings exist

# Without --strict, warnings are informational only
karandash validate
echo $?  # 0 even if warnings exist

CI/CD usage for strict mode:

# GitHub Actions
- run: karandash validate --strict
  continue-on-error: false

Exit Code 6 -- Execution Error

A plugin-related execution error occurred outside of validation.

Common causes: - Plugin JAR signing failed - Plugin compilation error - Plugin template generation failure - A plugin command's module failed to initialize (Error: plugin module '<id>' failed to initialize) - karandash lsp on a native binary (the language server ships with karandash.jar only)

karandash plugin sign my-plugin.jar --key private.key
echo $?  # 6 if signing fails

Exit Code 7 -- Global Timeout

The run exceeded the global watchdog timeout and was aborted. The timeout is set with the --global-timeout flag (or its config equivalent); 0 disables it.

karandash validate --mr-id 123 --platform github --project owner/repo --global-timeout 30s
echo $?  # 7 if the run does not finish within 30 seconds

Error Catalog Mapping

An exit code does not imply a catalog code: a message carries [EXXXX] only where the CLI raises that specific problem (for example E0005 when the --config path does not exist, E0100 when a platform token is missing). Other errors print without a code or docs link.

Exit Code Meaning
2 Config errors (a code is printed when one applies)
3 Provider errors (a code is printed when one applies)
1 Rule failures (not system errors)
4 Internal errors
5 Warnings in strict mode
6 Execution errors
7 Global watchdog timeout

Error Code Catalog

Every [EXXXX] code the CLI prints. The See: link in an error message points at its row here.

Code Title Category Severity
E0001 Unclosed string literal config error
E0002 Unknown rule name config error
E0003 Invalid regex pattern config error
E0004 Missing required field config error
E0005 Config file not found config error
E0006 Invalid YAML syntax config error
E0007 Unknown YAML config key config error
E0008 Invalid config value type config error
E0009 Remote config fetch failed config error
E0010 Circular config inheritance config error
E0011 Config inheritance depth exceeded config error
E0012 PR URL parse failed provider error
E0013 Config fetch authentication failed config error
E0014 Too many extends entries config error
E0015 Glob expansion failed config error
E0016 Condition evaluation failed config error
E0017 Extends manifest not found config error
E0018 Manifest set not found config error
E0019 Cache operation failed config warning
E0020 Glob security violation config error
E0021 Restricted env var in config config error
E0022 Environment variable not set config warning
E0023 External value resolution failed config error
E0024 Config inheritance chain too large config error
E0025 Unsupported config format config error
E0100 Authentication missing provider error
E0101 Authentication failed provider error
E0102 Unknown platform provider error
E0103 MR not found provider error
E0104 Rate limited provider warning
E0200 Title format mismatch validation error
E0201 Title length violation validation error
E0202 Missing required label validation error
E0203 Forbidden label present validation error
E0204 MR too large validation warning
E0300 Plugin load failed plugin error
E0301 Plugin init failed plugin error
E0302 Plugin declared but not installed plugin error
E0303 Unknown module reference in config plugin warning

Severity Levels

Validation findings have three severity levels:

Severity Effect on Exit Code Description
ERROR Exit code 1 Rule violation. Blocks merge.
WARNING Exit code 5 (strict) or 0 Advisory issue. Blocks only with --strict.
INFO No effect Informational message. Never affects exit code.

Scripting with Exit Codes

#!/bin/bash
karandash validate -c .karandash/config.yaml --mr-id "$MR_ID" --platform gitlab --project "$PROJECT"
EXIT_CODE=$?

case $EXIT_CODE in
    0) echo "All checks passed" ;;
    1) echo "Validation failed - fix the issues and retry" ;;
    2) echo "Configuration error - check .karandash/config.yaml" ;;
    3) echo "Provider error - check authentication" ;;
    4) echo "Internal error - please report this bug" ;;
    5) echo "Warnings detected (strict mode)" ;;
    6) echo "Execution error - check plugin configuration" ;;
    *) echo "Unknown exit code: $EXIT_CODE" ;;
esac

Exception Classes

Karandash maps exit codes to exception classes internally:

Exception Exit Code Usage
ConfigException 2 Invalid config, missing files, bad CLI usage
ProviderException 3 API errors, auth failures
KarandashException (varies) Base class for all typed errors

Config Inheritance Error Codes (E0015-E0020, E0024)

These error codes relate to config inheritance features: glob expansion, conditional extends, manifests, and caching.

E0015: Glob Expansion Failed

Exit Code: 2

[E0015] Glob expansion failed
Pattern: "{pattern}"
Reason: {reason}

Common causes: - Pattern syntax error (configs/[invalid].yaml) - Maximum expansion exceeded (>10 files matched) - Remote URL glob (not supported - use manifests) - Base directory doesn't exist

Fix: Use simple relative patterns (configs/*.yaml), keep depth under 5 levels, use manifests for remote globs.

E0016: Condition Evaluation Failed

Exit Code: 2

[E0016] Condition evaluation failed
Condition: "{condition}"
Error: {error_details}

Common causes: - Missing ${} wrapper: ENV == 'prod' should be ${ENV} == 'prod' - Invalid operator: only == and != are supported - Unclosed quotes or parentheses - Empty condition string

Valid syntax:

if: "${ENV} == 'production'"          # Variable comparison
if: "platform == 'gitlab'"            # Platform detection
if: "${A} == 'x' && ${B} == 'y'"     # AND
if: "${A} == 'x' || ${B} == 'y'"     # OR
if: "!${CI}"                          # NOT
if: "(${A} == 'x') || ${C} == 'z'"   # Parentheses

E0017: Extends Manifest Not Found

Exit Code: 2

[E0017] Extends manifest not found
File: {manifest_path}

Triggered when using @set-name syntax but .karandash/extends-manifest.yaml doesn't exist.

Fix: Create the manifest file or use direct extends instead.

E0018: Manifest Set Not Found

Exit Code: 2

[E0018] Manifest set not found
Reference: {set_name}
Available sets: {list}

Fix: Run karandash validate-extends --list-sets to see available sets. Check for typos (set names are case-sensitive).

E0019: Cache Operation Failed

Severity: WARNING (does not fail validation)

[E0019] Cache operation failed (warning)
Fallback: Using direct fetch

Common causes: Cache directory not writable, disk full, corrupted cache file.

Fix: Run karandash cache clear to reset cache. Check permissions on ~/.karandash/cache/extends/.

E0020: Glob Security Violation

Exit Code: 2

[E0020] Glob security violation
Pattern: {pattern}

Common causes: - Path traversal attempt (../../etc/passwd) - Absolute path (/etc/passwd) - Symlink escaping project boundary - Remote URL glob (https://example.com/*.yaml)

Fix: Use relative patterns within the project directory. Use manifests for remote URL lists.

E0024: Config Inheritance Chain Too Large

Exit Code: 2

[E0024] Config inheritance chain too large (max: {max} nodes)

Fix: Pull fewer configs into the extends chain, or raise limits.extends.max-chain-size in the root config.

E0025: Unsupported Config Format

Exit Code: 2

[E0025] Unsupported config format 'toml' for https://example.com/a.toml. Supported formats: .kts, .yaml, .yml, .json

Fix: Name the config file with a supported extension. Before this code existed the same condition was reported as E0012.


See Also