Skip to main content

Troubleshooting

This guide covers common issues you might encounter when using Dochia and how to resolve them.

Dochia Seems to be Stuck​

These are some common reasons why Dochia might appear to be stuck:

Network Issues​

  • Problem: Dochia might be waiting for a response from the server
  • Solution: Check network connection and server status
  • Debug: Use -vvv for verbose logging to see network activity

Server Issues​

  • Problem: The server might be slow or unresponsive
  • Solution: Check server logs and status
  • Workaround: Increase timeouts with --connection-timeout and --read-timeout

Many Fields in Requests​

  • Problem: If requests have many fields, Dochia takes longer as playbooks run for each field
  • Solution: Limit tested fields using --max-tested-fields
  • Example: --max-tested-fields 50 limits testing to 50 fields per playbook

Complex Schema Combinations​

  • Problem: anyOf/oneOf schemas generate tests for all possible combinations
  • Solution: Limit combinations with --max-schema-combinations
  • Example: --max-schema-combinations 10 limits to 10 combinations

Self-Reference in Schema​

  • Problem: Self-referencing schemas can cause infinite loops during request generation
  • Solution: Limit schema depth with --self-reference-depth
  • Example: --self-reference-depth 3 limits recursion to 3 levels

Progress Monitoring​

When running, Dochia shows progress as it processes paths. If the same playbook runs for a long time:

  1. Stop with Ctrl+C
  2. Run with increased verbosity: dochia test -c api.yaml -s http://localhost:8080 -vvv

Dochia is Not Generating Meaningful Values​

Problem​

Dochia generates values based on OpenAPI schema using patterns,examples, field names, and formats. Poor schema definition leads to meaningless values.

Solutions​

  1. Add Examples: Provide examples in your OpenAPI schema

    properties:
      email:
        type: string
        format: email
        example: "user@example.com"

  2. Use Standard Formats: Use well-known OpenAPI formats

    properties:
      birthDate:
        type: string
        format: date

  3. Check Supported Formats: Use dochia list --field-formats to see supported formats

  4. Use Custom Formats: Dochia supports custom formats beyond standard OpenAPI formats

    properties:
      currency:
        type: string
        format: currencyCode  # Generates valid ISO currency codes (USD, EUR, etc.)
      country:
        type: string
        format: countryCode   # Generates valid ISO country codes

Dochia is Generating Too Many Tests​

Problem​

Complex schemas or many fields result in excessive test generation.

Solutions​

  1. Limit Tested Fields: --max-tested-fields 100
  2. Test Specific Paths: --paths "/users,/orders"
  3. Test Specific Methods: --http-methods "POST,PUT"
  4. Use Specific Playbooks: --playbooks "NullValuesInFields,EmptyStringsInFields"
  5. Skip Unnecessary Playbooks: --skip-playbooks "VeryLargeStrings"

Example​

# Limit testing scope
dochia test -c api.yaml -s http://localhost:8080 \
  --paths "/users" \
  --http-methods "POST,PUT" \
  --max-tested-fields 20

Dochia Stops, Cannot Generate Values for Field​

Problem​

Complex regex patterns or poorly defined schemas prevent value generation.

Solutions​

  1. Simplify Patterns: Modify complex regex patterns in your schema
  2. Add Examples: Provide examples for problematic fields
  3. Use Custom Formats: Add custom formats using format

Example​

# Instead of complex pattern
properties:
  phoneNumber:
    type: string
    pattern: "^\\+?[1-9]\\d{1,14}$"
    
# Use custom format
properties:
  phoneNumber:
    type: string
    format: phone-number
    pattern: "^\\+?[1-9]\\d{1,14}$"

Dochia Report Takes Too Long to Open​

Problem​

Large number of tests creates oversized HTML reports.

Solutions​

  1. Use Different Output Format: --output-format HTML_ONLY (no JavaScript)
  2. Filter Results: --hide-success to hide successful tests
  3. Limit Test Scope: Use filtering options mentioned above

Example​

# Generate lightweight reports
dochia test -c api.yaml -s http://localhost:8080 \
  --output-format HTML_ONLY \
  --hide-success \
  --max-tested-fields 50

Dochia Generates Same Tests in Consecutive Runs​

Expected Behavior​

Unlike random fuzzers, Dochia uses deterministic playbooks. Same configuration = same tests.

For Randomness​

Use dochia fuzz for random testing:

# Random fuzzing with mutators
dochia fuzz -c api.yaml -s http://localhost:8080

Dochia Doesn't Generate Any Tests​

Common Causes​

  1. No Valid Paths: OpenAPI spec has no testable endpoints

    • Check: Verify your OpenAPI spec has valid paths with operations

  2. Restrictive Filters: All tests filtered out

    • Check: Review --skip-* arguments
    • Solution: Remove or adjust filters

  3. Non-existent Paths: Specified paths don't exist

    • Check: dochia list --paths -c api.yaml to see available paths
    • Solution: Use correct path names

  4. Playbook Selection: No playbooks match criteria

    • Check: dochia list --playbooks to see available playbooks
    • Solution: Adjust --playbooks argument

Debug Steps​

# Check available paths
dochia list --paths -c api.yaml

# Check available playbooks  
dochia list --playbooks

# Run with dry-run to see what would execute
dochia test -c api.yaml -s http://localhost:8080 --dry-run

Dochia Generates Invalid Tests​

Problem​

Some generated test cases don't make sense for your API.

Solutions​

  1. Filter Invalid Cases: Use skip options

    --skip-playbooks "VeryLargeStrings,RandomStringsInBooleanFields"

  2. Skip Specific Fields: --skip-fields "internalId,systemField"

  3. Skip HTTP Methods: --skip-http-methods "TRACE,OPTIONS"

  4. Skip Field Types: --skip-field-types "binary"

  5. Skip Headers: --skip-headers "X-Internal-Header"

Example​

# Skip problematic test types
dochia test -c api.yaml -s http://localhost:8080 \
  --skip-playbooks "VeryLargeStrings" \
  --skip-fields "id,createdAt" \
  --skip-http-methods "TRACE"

Native Binary Specific Issues​

Dynamic Configuration Issues​

  • Problem: Custom scripts or dynamic values don't work
  • Solution: Use supported Java classes (see Limitations)

Platform Issues​

  • Problem: Binary doesn't run on your platform
  • Solution: Use Docker version 
    docker run --rm -v $(pwd):/workspace dochiadev/dochia-cli:latest test -c /workspace/api.yaml -s http://localhost:8080

Authentication Issues​

Token Expiration​

# Use token refresh
dochia test -c api.yaml -s http://localhost:8080 \
  --header "Authorization=auth_script" \
  --auth-refresh-script "get-token.sh" \
  --auth-refresh 300

Certificate Issues​

# Use client certificates
dochia test -c api.yaml -s https://localhost:8443 \
  --ssl-keystore keystore.p12 \
  --ssl-keystore-password password

Performance Issues​

Slow Execution​

  1. Reduce Rate Limiting: --max-requests-per-minute 5000
  2. Increase Timeouts: --connection-timeout 30 --read-timeout 30
  3. Limit Scope: Use path and method filters
  4. Skip Heavy Playbooks: --skip-playbooks "LargeNumberOfRandomHeaders"

High Memory Usage​

  1. Limit Field Testing: --max-tested-fields 100
  2. Limit Schema Combinations: --max-schema-combinations 10
  3. Skip Field Types: --skip-field-types "binary"
  4. Skip Playbooks: --skip-playbooks "VeryLargeStrings"

Getting Debug Information​

Environment Info​

# Get system and environment details
dochia info

Verbose Logging​

# Maximum verbosity
dochia test -c api.yaml -s http://localhost:8080 -vvv

Dry Run Analysis​

# See what will be tested without execution
dochia test -c api.yaml -s http://localhost:8080 --dry-run

Reporting Issues​

If you encounter a bug or unexpected behavior:

  1. Gather Information:

    • Dochia version: dochia --version
    • Environment info: dochia info
    • Command used and error output

  2. Create Minimal Example:

    • Simplify OpenAPI spec to reproduce issue
    • Use minimal command arguments

  3. Report Issue:

    • GitHub Issues: dochia-cli issues
    • Include version, environment, and reproduction steps

Quick Diagnostic Checklist​

When Dochia isn't working as expected:

  • Check Dochia version: dochia --version
  • Validate OpenAPI spec with online validators
  • Test server accessibility: curl http://your-server/health
  • Run with dry-run: --dry-run
  • Check available paths: dochia list --paths -c api.yaml
  • Increase verbosity: -vvv
  • Review command arguments for typos
  • Check system resources (memory, disk space)
  • Verify network connectivity and firewall settings