Troubleshooting Guide

Having issues with Voyager Verifier? This guide helps you quickly diagnose and resolve problems.

Quick Problem Solver

Verification Failed?
        ↓
┌─────────────────────────────────┐
│ Check Error Code                │
│ → See Error Codes Reference     │
└─────────────────────────────────┘
        ↓
┌─────────────────────────────────┐
│ Common Error?                   │
│ → See Common Errors Guide       │
└─────────────────────────────────┘
        ↓
┌─────────────────────────────────┐
│ Need More Details?              │
│ → Use Verbose Mode              │
└─────────────────────────────────┘
        ↓
┌─────────────────────────────────┐
│ Still Stuck?                    │
│ → Follow Debugging Workflow     │
└─────────────────────────────────┘
        ↓
┌─────────────────────────────────┐
│ Need Help?                      │
│ → Contact Support               │
└─────────────────────────────────┘

Troubleshooting Resources

1. Common Errors

Quick fixes for frequent problems

Start here if you’re encountering a common issue:

• Compilation errors
• Verification failures
• Configuration problems
• Network and API errors
• File and project errors
• Class hash issues

When to Use: You have an error and want a quick solution.

2. Debugging Guide

Systematic troubleshooting workflow

Follow the step-by-step debugging process:

• 6-step debugging workflow
• Debugging tools (dry-run, verbose, local testing, history)
• Common debugging scenarios
• Advanced debugging techniques

When to Use: Quick fixes didn’t work and you need a systematic approach.

3. Verbose Mode

Understanding detailed output

Learn how to use --verbose for detailed error information:

• Enabling verbose mode
• Interpreting verbose output
• Common verbose patterns
• Debugging with verbose mode

When to Use: You need more details about what’s failing.

4. Getting Support

How to get help

Find support resources:

• Self-help documentation
• Telegram community
• GitHub issues
• Bug reporting guidelines

When to Use: You’ve tried everything and need human assistance.

Quick Tips

Compilation Failed?

# Build locally first
scarb --release build

# Check for syntax errors
scarb check

Verification Failed?

# Use verbose mode to see details
voyager status --network mainnet --job <JOB_ID> --verbose

# Preview what will be submitted
voyager verify --dry-run ...

Module Not Found?

# Include test files if needed
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract \
  --test-files

Class Hash Mismatch?

# Include Scarb.lock for reproducibility
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract \
  --lock-file

Network Issues?

# Check API status
curl https://api.voyager.online/api-docs

# Try a different network
voyager verify --network sepolia ...

Job Taking Too Long?

# Check job status
voyager status --network mainnet --job <JOB_ID>

# View recent jobs
voyager history --network mainnet --limit 5

Error Code Quick Reference

See Error Codes Reference for complete details.

Common Scenarios

Scenario 1: First-Time Verification

Problem: Not sure where to start?

Solution:

# 1. Build your contract
cd my-project
scarb --release build

# 2. Get your class hash from declaration
# Example: 0x044dc2b3...

# 3. Verify with basic command
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract

# 4. Check status
voyager status --network mainnet --job <JOB_ID>

Learn More: Getting Started Guide

Scenario 2: Test Files Missing

Problem: Error E005 - Module file not found (test files)

Solution:

# Include test files in verification
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract \
  --test-files

Learn More: Test Files Guide

Scenario 3: Class Hash Mismatch

Problem: Error E030 - Compiled hash doesn’t match expected

Solution:

# 1. Include Scarb.lock for reproducibility
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract \
  --lock-file

# 2. Ensure exact same versions
cat Scarb.toml  # Check Cairo/Scarb versions

# 3. Use dry-run to debug
voyager verify --dry-run ... --verbose

Learn More: Lock Files Guide

Scenario 4: Multi-Package Workspace

Problem: Which package to verify in a workspace?

Solution:

# List available packages
scarb metadata

# Verify specific package
voyager verify --network mainnet \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract \
  --package my_package

Learn More: Multi-Package Guide

Scenario 5: Custom Network/Endpoint

Problem: Need to verify on custom network?

Solution:

# Use custom endpoint
voyager verify --network custom \
  --endpoint https://api.custom.com \
  --class-hash 0x044dc2b3... \
  --contract-name MyContract

Learn More: Custom Endpoints Guide

Debugging Checklist

Before asking for help, complete this checklist:

• Read the error message - What error code (E###) are you seeing?
• Check Common Errors - Is your error listed?
• Use verbose mode - Run with --verbose flag
• Try dry-run - Use --dry-run to preview submission
• Verify locally - Can you build with scarb build?
• Check versions - Are Cairo/Scarb versions correct?
• Review command - Are all required flags present?
• Test network - Is the API endpoint responding?
• Check history - Have similar verifications succeeded before?

Troubleshooting Tools

1. Verbose Mode

Get detailed error information:

voyager verify --verbose ...
voyager status --verbose ...

See: Verbose Mode Guide

2. Dry-Run Mode

Preview submission without sending:

voyager verify --dry-run ...

See: Debugging Guide

3. History Command

Check previous verifications:

# Recent jobs
voyager history --network mainnet --limit 10

# Successful jobs only
voyager history --network mainnet --status verified

# Specific contract
voyager history --network mainnet --contract MyContract

See: History Command Guide

4. Local Testing

Test before submitting:

# Build locally
scarb --release build

# Check for errors
scarb check

# Run tests
scarb test

Prevention Tips

✅ Best Practices

1. Always build locally first

   scarb --release build
   

2. Use lock files for reproducibility

   # Commit Scarb.lock to version control
   git add Scarb.lock
   

3. Test with dry-run before submitting

   voyager verify --dry-run ...
   

4. Use verbose mode when debugging

   voyager verify --verbose ...
   

5. Keep versions consistent

   # In Scarb.toml
   [dependencies]
   starknet = "2.8.2"
   

6. Include necessary files

   # Include tests if they're imported
   voyager verify --test-files ...
   

Getting Help

Self-Help First

1. Check Common Errors
2. Review Error Codes Reference
3. Use Debugging Workflow
4. Try Verbose Mode

Community Support

• Telegram: https://t.me/StarknetVoyager
• GitHub Issues: https://github.com/NethermindEth/voyager-verifier/issues

See: Getting Support Guide

See Also

Troubleshooting Resources

• Common Errors - Quick fixes for frequent problems
• Debugging Guide - Systematic troubleshooting workflow
• Verbose Mode - Understanding detailed output
• Getting Support - How to get help

Reference Material

• Error Codes - Complete error reference (E001-E042)
• Supported Versions - Version compatibility
• File Collection - What files are included

Feature Guides

• Core Features - Essential functionality
• Advanced Features - Advanced usage patterns
• Getting Started - Initial setup and usage