Troubleshooting Guide
This guide helps you resolve common issues when using Karandash for merge request validation. Follow the sections below to diagnose and fix problems.
Authentication Issues
Missing or Invalid Token
Problem: Validation fails with "authentication failed" or "unauthorized"
Root Cause: Token not set, expired, or has insufficient permissions
Solution:
- Verify your token is set as an environment variable: ```bash # GitHub export GITHUB_TOKEN="your-token-here"
# GitLab export GITLAB_TOKEN="your-token-here"
# Bitbucket export BITBUCKET_TOKEN="your-token-here" ```
- Check token permissions:
- GitHub: Requires
reposcope for private repos,public_repofor public - GitLab: Requires
apiscope minimum -
Bitbucket: Requires
repository:readandpullrequest:read -
Verify token is not expired: ```bash # Test GitHub token curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user
# Test GitLab token curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" https://gitlab.com/api/v4/user ```
- If token is invalid, regenerate it in your platform:
- GitHub Personal Access Tokens
- GitLab Personal Access Tokens
- Bitbucket App Passwords
Token Permissions Insufficient
Problem: "Permission denied" error during validation
Root Cause: Token has limited scopes or user lacks repository access
Solution:
- Verify you have repository access on the platform
- Check your token has the required scopes:
bash # GitHub: List token scopes curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user -I | grep X-OAuth-Scopes - Create a new token with broader permissions if needed
- For CI/CD, use repository-specific tokens or service accounts with minimal required access
Platform-Specific Auth Problems
GitHub: OAuth app rate limits or suspended token - Solution: Check OAuth app status, regenerate token
GitLab: API version mismatch on self-hosted instances - Solution: Verify API version compatibility (see Platform-Specific Issues)
Bitbucket: Workspace vs. user permissions - Solution: Make sure token user has access to the workspace containing the repository
Configuration Errors
Config File Not Found
Problem: "Configuration file not found" warning during startup
Root Cause: Karandash cannot locate .karandash/config.kts, .karandash/config.yaml, or .karandash/config.json
Solution:
-
Create a configuration file in your project root:
bash karandash init -
Verify the file exists:
bash ls -la .karandash/config.kts -
Use explicit path if needed:
bash karandash validate --config /path/to/config.kts -
For zero-config mode (uses sensible defaults, no config file needed):
bash karandash validate
Invalid YAML/JSON Syntax
Problem: "YAML syntax error" or "JSON parse error" when loading config
Root Cause: Malformed YAML indentation or JSON structure
Solution:
- Validate YAML syntax: ```bash # Using yamllint if available yamllint .karandash/config.yaml
# Or manually check indentation (spaces, not tabs) cat -A .karandash/config.yaml | grep "^I" # Shows tabs ```
-
Validate JSON syntax:
bash jq empty .karandash/config.json -
Common YAML issues:
- Use 2-space indentation (not tabs or 4 spaces)
- Quote strings containing special characters:
pattern: "^(feat|fix):" - Use
|for multiline strings -
Use
>for folded multiline strings -
Example valid YAML config:
yaml karandash: rules: titleFormat: pattern: "^(feat|fix|docs):" minLength: 10
Invalid Kotlin DSL Syntax
Problem: "Syntax error in .karandash/config.kts" during parsing
Root Cause: Invalid Kotlin syntax or DSL usage
Solution:
-
Verify Kotlin syntax in
.karandash/config.kts:text // Correct syntax karandash { rules { titleFormat { pattern = "^(feat|fix):" // Use = for assignments minLength = 10 } } } -
Common mistakes:
- Missing
=in property assignments - Unclosed braces
{} - Missing commas in lists:
listOf("a", "b") -
Using
==instead of=for property assignment -
Check for typos in rule names (case-sensitive):
text titleFormat { } // Correct TitleFormat { } // Wrong - case sensitive title_format { } // Wrong - use camelCase
Unknown Rule Names
Problem: "Unknown rule 'xyz'" or rule not recognized during validation
Root Cause: Rule name misspelled or rule doesn't exist
Solution:
- Use only valid rule names:
titleFormat- Title validationcommitMessages- Commit message validationjiraTicket- JIRA ticket referencebranchNaming- Branch naming conventionsfileChanges- File-based rulescodeowners- CODEOWNERS complianceapprovals- Approval requirementsreviewers- Reviewer requirementscicdStatus- CI/CD pipeline statusconflictDetection- Merge conflictsdraftDetection- Draft/WIP statuslabels- Label requirementssizeLimits- Change size limitssecurity- Secret scanning-
conditional- Conditional rules -
Check rule name spelling and case:
```kotlin // Correct titleFormat { pattern = "^feat:" }
// Incorrect - unknown rule title_format { pattern = "^feat:" } ```
Missing Required Fields
Problem: "Missing required field 'X'" error during validation
Root Cause: Configuration missing mandatory properties for a rule
Solution:
- Check required fields for each rule type (varies by rule)
-
For conditional rules, always specify at least:
text conditional { when { // At least one condition required filePathMatches("src/.*") } then { // At least one validation required requireApprovals(1) } } -
For file change rules, every pattern entry needs a
pattern:kotlin fileChanges { patterns = listOf( FilePatternRule( pattern = "db/migrations/**", // required requireApproval = listOf("dba-team") ) ) }
Type Mismatches
Problem: "Type mismatch: expected String, got Integer" or similar
Root Cause: Wrong data type used for configuration property
Solution:
-
Use correct types for each property:
kotlin // Correct types minLength = 10 // Int pattern = "^feat:" // String requiredApprovers = listOf("a") // List<String> requiresDescription = true // Boolean -
Common type mistakes:
kotlin minLength = "10" // Wrong - should be Int maxLength = 72.5 // Wrong - should be Int, not Double requiresDescription = "true" // Wrong - should be Boolean
Platform-Specific Issues
GitHub Rate Limiting
Problem: "API rate limit exceeded" or "403 Forbidden" during validation
Root Cause: GitHub API rate limit reached (60 requests/hour unauthenticated, 5000/hour authenticated)
Solution:
- Use authenticated requests (already configured if
GITHUB_TOKENis set) - Reduce API calls:
bash # Use file mode to validate locally without live API calls karandash validate --mr mr_data.json - Wait for rate limit reset (1 hour from first request)
- Check rate limit status:
bash curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/rate_limit
GitLab API Version Mismatch
Problem: "API version not supported" on self-hosted GitLab
Root Cause: Self-hosted instance running older GitLab version incompatible with Karandash
Solution:
-
Check your GitLab version:
bash curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \ https://your-gitlab.com/api/v4/version -
Make sure GitLab version 13.0 or later (for full API compatibility)
- For older versions, some features may not work:
- Draft MR detection requires GitLab 13.2+
-
CODEOWNERS validation requires GitLab 13.0+
-
Upgrade GitLab if possible, or use only compatible rules
Bitbucket Authentication
Problem: "Bitbucket authentication failed" or "401 Unauthorized"
Root Cause: Invalid app password or workspace permissions issue
Solution:
-
Verify app password is set correctly:
bash export BITBUCKET_TOKEN="your-app-password" -
Make sure app password has correct permissions:
repository:read- Read repository data-
pullrequest:read- Read pull request data -
Check workspace access:
bash curl -u "username:$BITBUCKET_TOKEN" \ https://api.bitbucket.org/2.0/user -
For Bitbucket Server (self-hosted):
- Use
BITBUCKET_SERVER_TOKENinstead - Set API endpoint:
BITBUCKET_SERVER_URL=https://your-server.com
Self-Hosted Instance Configuration
Problem: "Cannot connect to self-hosted instance" or "SSL certificate error"
Root Cause: Incorrect API endpoint or SSL/TLS issues
Solution:
- Set correct API endpoint for self-hosted instances: ```bash # GitLab self-hosted export GITLAB_URL="https://gitlab.company.com"
# Gitea self-hosted export GITEA_URL="https://gitea.company.com" ```
-
Handle SSL certificate warnings:
bash # Add the certificate to the trusted store # On macOS: security add-trusted-cert /path/to/cert.pem # On Linux: sudo cp cert.pem /usr/local/share/ca-certificates/ -
Test connectivity:
bash curl -v -H "Authorization: token $TOKEN" \ $API_ENDPOINT/user
Network and Proxy Issues
Problem: "Network timeout" or "Cannot connect to server"
Root Cause: Firewall, proxy, or DNS resolution issues
Solution:
-
Test basic connectivity:
bash ping api.github.com curl -v https://api.github.com/user -
Configure proxy if behind corporate firewall:
bash export HTTP_PROXY="http://proxy.company.com:8080" export HTTPS_PROXY="https://proxy.company.com:8080" -
Configure proxy authentication:
bash export HTTP_PROXY="http://username:password@proxy.com:8080" -
Set longer HTTP timeout via environment variable for slow connections:
bash KARANDASH_HTTP_TIMEOUT=60 karandash validate
Validation Errors
"MR Not Found" Error
Problem: "Merge request #123 not found" during validation
Root Cause: MR ID doesn't exist, wrong repository, or insufficient permissions
Solution:
- Verify MR exists: ```bash # GitHub curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/owner/repo/pulls/123
# GitLab curl -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \ https://gitlab.com/api/v4/projects/owner%2Frepo/merge_requests/123 ```
-
Check repository path:
bash karandash validate owner/repo#123 -
Verify token has access to the repository:
bash # GitHub curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/owner/repo
"Permission Denied" Error
Problem: "Permission denied" or "access forbidden" during validation
Root Cause: Token user doesn't have permission to read repository or MR
Solution:
- Verify user has repository access on the platform
-
Check token has correct scopes:
bash # GitHub curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/user -I | grep X-OAuth-Scopes -
For private repositories, make sure token has
reposcope (GitHub) orapiscope (GitLab) - Request access or use a different token with appropriate permissions
API Error Responses (4xx, 5xx)
Problem: "HTTP 400", "HTTP 401", "HTTP 500" errors
Root Cause: API error from platform (varies by status code)
Solution:
| Status | Cause | Fix |
|---|---|---|
| 400 | Invalid request parameters | Check API endpoint and query parameters |
| 401 | Unauthorized | Verify authentication token is valid and set |
| 403 | Forbidden | Check token permissions and repository access |
| 404 | Not found | Verify MR/repo exists and path is correct |
| 429 | Rate limited | Wait for reset or use authenticated requests |
| 500 | Server error | Retry after a short delay; contact platform support |
| 503 | Service unavailable | Platform maintenance; retry later |
Example debugging:
# Enable verbose output to see full error
karandash validate --verbose
# Check platform status page
# GitHub: https://status.github.com
# GitLab: https://status.gitlab.com
Timeout Issues
Problem: "Request timeout" or validation hangs
Root Cause: Network latency, large MR, or slow API response
Solution:
-
Increase HTTP timeout via environment variable:
bash KARANDASH_HTTP_TIMEOUT=120 karandash validate -
Check network latency:
bash ping -c 5 api.github.com curl -w "Time: %{time_total}s\n" https://api.github.com/user -
Validate locally without API calls using file mode:
bash karandash validate --mr mr_data.json -
Check for slow rules:
bash karandash validate --verbose # Shows timing per rule
Performance Issues
Slow Validation Speed
Problem: Validation takes 10+ seconds for a single MR
Root Cause: Network latency, large MR analysis, or expensive plugin operations
Solution:
-
Profile validation to find bottlenecks:
bash karandash validate --profile -
Disable unnecessary rules:
kotlin karandash { rules { // Only enable rules you need titleFormat = true // security rule is expensive - disable if not needed security = false } } -
Optimize rule configuration: ```kotlin // Bad: Expensive regex with backtracking commitMessages { pattern = "^(feat|fix|chore|refactor|perf|test|docs|style|build|ci|revert)(.+)?!?:(.+)$" }
// Better: Simple pattern commitMessages { pattern = "^[a-z]+:" } ```
- Use file mode to avoid live API calls:
bash karandash validate --mr mr_data.json
Large MR Handling
Problem: Validation fails or times out on MRs with 100+ files or 1000+ line changes
Root Cause: Memory constraints or API payload size limits
Solution:
-
Split large MR into multiple smaller ones - Karandash validates all changed files; the
sizeLimitsrule flags MRs that grow past a reviewable size:kotlin rules { sizeLimits { maxFiles = 100 maxLines = 1000 } } -
Disable expensive rules for large MRs:
text conditional { when { commitCount > 100 } then { // Skip expensive security scan security { enabled = false } } } -
Increase memory for Karandash (JVM distribution only - native binary manages memory automatically):
bash export JAVA_OPTS="-Xmx2g" java -jar karandash.jar validate -
Use streaming output for large result sets:
bash karandash validate --format sarif --output results.sarif
Plugin Performance Issues
Problem: Validation is slow when plugins are loaded
Root Cause: Plugin initialization overhead or inefficient plugin code
Solution:
-
Identify slow plugins:
bash karandash validate --profile # Shows per-plugin timing -
Disable unused plugins:
kotlin karandash { plugins { // Remove or disable unused plugins } } -
Check plugin implementation:
- Make sure plugins use async operations where possible
- Avoid repeated API calls
-
Cache external data
-
Report performance issues to plugin author
Memory Issues
Problem: "Out of memory" error or process crashes
Root Cause: Large MRs exceeding available heap memory
Solution:
-
Increase JVM heap memory (JVM distribution only - native binary uses fixed low memory footprint):
bash export JAVA_OPTS="-Xmx4g" # Set to 4GB java -jar karandash.jar validate -
Check available memory:
bash # Linux/macOS free -h # or: vm_stat -
Keep MRs within a size the run can hold using the
sizeLimitsrule:kotlin rules { sizeLimits { maxFiles = 100 } } -
Disable memory-intensive rules:
kotlin rules { security = false // Most memory-intensive }
CI/CD Problems
Non-Zero Exit Codes
Problem: CI job fails with exit code 1, 2, or other non-zero values
Root Cause: Validation failures or errors during execution
Solution:
| Exit Code | Meaning | Fix |
|---|---|---|
| 0 | Success | No action needed |
| 1 | Validation failed | Fix violations in MR |
| 2 | Configuration error | Fix config file syntax |
| 3 | Authentication error | Verify token is set |
| 4 | MR not found | Verify MR ID is correct |
Example CI configuration:
# GitLab CI
validate_mr:
script:
- karandash validate
allow_failure: false # Fail job if validation fails
Output Format Issues
Problem: Output is malformed or missing expected fields
Root Cause: Wrong output format specified or incompatible with consumer
Solution:
-
Check supported output formats:
bash karandash validate --format json # JSON format karandash validate --format sarif # SARIF format karandash validate --format console # Human-readable console output (default) -
Validate JSON output:
bash karandash validate --format json | jq empty -
For SARIF, validate against schema: ```bash # Install sarif tool npm install -g @microsoft/sarif-multitool
# Validate sarif validate results.sarif ```
Comment Posting Failures
Problem: Results comment fails to post to MR
Root Cause: Insufficient permissions or API quota exhausted
Solution:
- Verify token has comment posting permission:
- GitHub:
pull_requests:writescope -
GitLab:
apiscope with write access -
Check for API quota:
bash # GitHub: Rate limit curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/rate_limit -
Disable auto-comment if not needed (set in config):
yaml reporters: markdown: false -
Check MR status (cannot comment on closed/merged MRs):
bash # Verify MR is open curl -H "Authorization: token $GITHUB_TOKEN" \ https://api.github.com/repos/owner/repo/pulls/123 \ | jq .state
Watch Mode in CI/CD
Problem: "Watch mode not supported in CI/CD" warning
Root Cause: Watch mode requires interactive terminal
Solution:
-
Disable watch mode in CI/CD:
bash # Use normal validation instead karandash validate --once -
Watch mode is for local development only: ```bash # Local: Works fine karandash validate --watch
# CI/CD: Use standard mode karandash validate ```
Plugin Issues
Plugin Not Found
Problem: "Plugin 'xyz' not found" during startup
Root Cause: Plugin not installed or incorrect plugin name
Solution:
-
List available plugins:
bash karandash plugin list -
Install missing plugin: ```bash karandash plugin install plugin-name
# Or from registry karandash plugin install @registry/plugin-name ```
- Check plugin name in configuration:
kotlin plugins { plugin("plugin-name") { // Must match exactly version = "1.0.0" } }
Plugin Load Errors
Problem: "Failed to load plugin" or plugin initialization error
Root Cause: Plugin incompatibility, missing dependencies, or corrupted plugin JAR
Solution:
-
Check plugin compatibility:
bash karandash plugin info plugin-name -
Verify plugin version matches Karandash version:
bash karandash --version karandash plugin info plugin-name | grep Version -
Reinstall plugin:
bash karandash plugin uninstall plugin-name karandash plugin install --registry plugin-name -
Check the karandash version the plugin requires:
bash karandash plugin info plugin-name --dependencies -
Enable debug logging:
bash karandash --debug validate
Native Plugin Compilation
Problem: "Failed to compile native plugin" or linking errors
Root Cause: Missing build tools or incompatible C/C++ code
Solution:
- Verify build tools are installed: ```bash # macOS xcode-select --install
# Linux sudo apt-get install build-essential
# Windows # Install Visual Studio Build Tools ```
-
Find the installed plugin file:
bash karandash plugin info plugin-name --source -
Reinstall the registry build (fresh download, checksum-verified):
bash karandash plugin rebuild plugin-name -
Check compilation logs:
bash karandash --debug validate 2>&1 | grep -i "compile\|error"
Plugin Compatibility
Problem: "Plugin incompatible with current Karandash version"
Root Cause: Plugin built for different Karandash version
Solution:
-
Check plugin version requirements:
bash karandash plugin info plugin-name -
Upgrade or downgrade plugin: ```bash # Upgrade karandash plugin install plugin-name@latest
# Specific version karandash plugin install plugin-name@1.2.0 ```
-
Check Karandash version:
bash karandash --version -
Upgrade Karandash if plugin requires newer version:
bash brew upgrade karandash
Common Error Messages
"Config validation failed: unknown rule 'xyz'"
Error Text: Config validation failed: unknown rule 'xyz'
Root Cause: Typo in rule name or rule doesn't exist
Solution:
- Check rule name spelling (case-sensitive)
- See rule names list in "Unknown Rule Names" section above
- Run karandash explain to see the rules in the effective config
See Also: Unknown Rule Names
"Failed to authenticate: invalid token"
Error Text: Failed to authenticate: invalid token
Root Cause: Token is expired, revoked, or has insufficient permissions
Solution: - Verify token environment variable is set correctly - Regenerate token on platform - Check token permissions
See Also: Missing or Invalid Token
"MR not found: could not retrieve merge request details"
Error Text: MR not found: could not retrieve merge request details
Root Cause: MR ID doesn't exist or user lacks access
Solution: - Verify MR ID is correct - Check token has repository access - Make sure MR is open (not closed/merged)
See Also: "MR Not Found" Error
"Configuration file not found: no config at .karandash/config.kts or .karandash/config.yaml"
Error Text: Configuration file not found: no config at .karandash/config.kts or .karandash/config.yaml
Root Cause: No config file in project root
Solution:
- Run karandash init to create default config
- Place config in project root or use --config flag
See Also: Config File Not Found
"YAML parse error at line X: expected key"
Error Text: YAML parse error at line X: expected key
Root Cause: YAML indentation or syntax error
Solution:
- Check indentation (2 spaces, not tabs)
- Verify quotes around strings with special characters
- Use yamllint tool to validate
See Also: Invalid YAML/JSON Syntax
"API rate limit exceeded: 429 Too Many Requests"
Error Text: API rate limit exceeded: 429 Too Many Requests
Root Cause: Too many API requests in short timeframe
Solution: - Wait 1 hour for rate limit reset - Use authenticated requests - Reduce validation frequency in CI/CD
See Also: GitHub Rate Limiting
"Request timeout: connection timeout after 30s"
Error Text: Request timeout: connection timeout after 30s
Root Cause: Network latency or slow API response
Solution:
- Increase HTTP timeout: KARANDASH_HTTP_TIMEOUT=60 karandash validate
- Check network connectivity
- Check platform status page
See Also: Timeout Issues
Getting Help
If you can't resolve your issue:
- Check this troubleshooting guide first
- Search GitHub Issues
- Check Documentation
- Open a New Issue with:
- Karandash version:
karandash --version - OS and platform:
uname -a - Configuration file (sanitized)
- Full error message with
--verboseflag - Steps to reproduce