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 ~):

   json

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

3. •

   Clean install after version changes:

   bash

   rm -rf node_modules package-lock.json
   npm ci
   

4. •

   Recompile contracts after compiler update:

   bash

   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:

   bash

   rm -rf node_modules/.cache
   

3. •

   Verify correct Node version:

   bash

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

4. •

   Reinstall node_modules:

   bash

   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:

   bash

   npm view @midnight-ntwrk/compact-runtime
   

2. •

   Clear npm cache:

   bash

   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