Midnight Environment Debugging

Expert knowledge for identifying and resolving common Midnight development toolchain issues.

Diagnostic Approach

When encountering Midnight-related errors, follow this systematic approach:

1. Identify the error category (see Error Categories below)
2. Check cache freshness - Run /midnight:sync-releases if version info needed
3. Run diagnostics - Use /midnight:doctor for comprehensive checks
4. Apply targeted fixes - Use the solutions from this skill
5. Verify the fix - Run /midnight:check to confirm

For comprehensive diagnostics:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.py

Error Categories

1. PATH and Installation Errors

Symptom: compact: command not found

Diagnosis:

# Check if compact exists somewhere
ls -la ~/.compact/bin/compact 2>/dev/null || echo "Not in default location"

# Check PATH
echo $PATH | tr ':' '\n' | grep -i compact

Solutions:

2. Version Mismatch Errors

Symptoms:

• Runtime errors mentioning version incompatibility
• Build failures after updating one component
• pragma language_version mismatches

Diagnosis:

# Check current versions
compact compile --version
npm list @midnight-ntwrk/compact-runtime
npm list @midnight-ntwrk/ledger

Key Rule: All Midnight components must use compatible versions per the support matrix.

Solutions:

1. Check the compatibility matrix in cached release notes or run /midnight:versions

2. Use exact versions in package.json (no ^ or ~):

   jsonCopy

   {
     "dependencies": {
       "@midnight-ntwrk/compact-runtime": "0.9.0",
       "@midnight-ntwrk/ledger": "4.0.0"
     }
   }
   

3. Clean install after version changes:

   bashCopy

   rm -rf node_modules package-lock.json
   npm ci
   

4. Recompile contracts after compiler update:

   bashCopy

   rm -rf contract/*.cjs contract/*.prover contract/*.verifier
   compact compile src/contract.compact contract/
   

See references/version-mismatch-guide.md for detailed version troubleshooting.

3. Node.js Import Errors

Symptom: ERR_UNSUPPORTED_DIR_IMPORT

Causes:

• Stale terminal environment after Node version switch
• Cached module references
• Wrong Node.js version active

Solutions:

1. Open a new terminal window (not just source profile)

2. Clear module cache:

   bashCopy

   rm -rf node_modules/.cache
   

3. Verify correct Node version:

   bashCopy

   node --version  # Should be 18+
   nvm use 18      # If using nvm
   

4. Reinstall node_modules:

   bashCopy

   rm -rf node_modules
   npm install
   

4. Proof Server Issues

Symptoms:

• Connection refused on port 6300
• Wallet cannot generate proofs
• "Proof server not responding"

Diagnosis:

# Check if running
docker ps | grep proof-server

# Check if port is available
lsof -i :6300

# Check Docker is running
docker info

Solutions:

5. Compilation Errors

Symptoms:

• Contract compilation fails
• Type errors in Compact code
• Circuit generation errors

Diagnosis:

# Check compiler version matches pragma
compact compile --version

# In contract file, check pragma:
# pragma language_version 0.18;

Common Issues:

6. Package Installation Errors

Symptoms:

• npm install fails for @midnight-ntwrk packages
• Peer dependency conflicts
• Registry errors

Solutions:

1. Check npm registry access:

   bashCopy

   npm view @midnight-ntwrk/compact-runtime
   

2. Clear npm cache:

   bashCopy

   npm cache clean --force
   

3. Use exact versions to avoid peer conflicts

4. Don't mix lockfiles - use only package-lock.json (npm) OR bun.lock (Bun)

Quick Diagnostic Commands

Error Message Reference

See references/common-errors.md for a complete catalog of error messages and their solutions.

When to Seek Additional Help

If standard troubleshooting doesn't resolve the issue:

1. Check the Midnight FAQ
2. Review the Getting Help section
3. Join the Midnight developer community channels