---
name: midnight-tooling-midnight-debugging
description: Use when encountering Midnight errors like "compact: command not found", "ERR_UNSUPPORTED_DIR_IMPORT", version mismatches, proof server failures, "@midnight-ntwrk" package errors, or compilation failures.
---

# 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:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/scripts/doctor.py
```

## Error Categories

### 1. PATH and Installation Errors

**Symptom**: `compact: command not found`

**Diagnosis**:
```bash
# 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**:

| Cause | Fix |
|-------|-----|
| Not installed | Run Compact installer (see midnight-setup skill) |
| Not in PATH | Add `export PATH="$HOME/.compact/bin:$PATH"` to shell profile |
| Wrong shell profile | Edit `~/.zshrc` (macOS) or `~/.bashrc` (Linux) |
| Profile not sourced | Open a **new** terminal window |

### 2. Version Mismatch Errors

**Symptoms**:
- Runtime errors mentioning version incompatibility
- Build failures after updating one component
- `pragma language_version` mismatches

**Diagnosis**:
```bash
# 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**:
```bash
# Check if running
docker ps | grep proof-server

# Check if port is available
lsof -i :6300

# Check Docker is running
docker info
```

**Solutions**:

| Issue | Fix |
|-------|-----|
| Not running | `docker run -p 6300:6300 midnightnetwork/proof-server -- midnight-proof-server --network testnet` |
| Port in use | Stop other process: `kill $(lsof -t -i:6300)` or use different port |
| Docker not running | Start Docker Desktop |
| Image not pulled | `docker pull midnightnetwork/proof-server:latest` |
| Wrong network | Ensure `--network testnet` matches your target |

### 5. Compilation Errors

**Symptoms**:
- Contract compilation fails
- Type errors in Compact code
- Circuit generation errors

**Diagnosis**:
```bash
# Check compiler version matches pragma
compact compile --version

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

**Common Issues**:

| Error | Cause | Fix |
|-------|-------|-----|
| Pragma mismatch | Contract declares different version | Update pragma or switch compiler version |
| Type errors | Language feature changed | Check release notes for breaking changes |
| Circuit too large | Complex computation | Simplify logic or split into multiple transactions |

### 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

| Check | Command |
|-------|---------|
| All tool versions | `/midnight:check` |
| Comprehensive diagnostic | `/midnight:doctor` |
| Current vs latest versions | `/midnight:versions` |
| Component changelog | `/midnight:changelog compact` |

## 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](https://docs.midnight.network/develop/faq)
2. Review the [Getting Help](https://docs.midnight.network/getting-started/getting-help) section
3. Join the Midnight developer community channels


---
Source attribution: aaronbassett
Original project: https://github.com/aaronbassett/midnight-knowledgebase/blob/8d873d378dc993f3b80e611d44605ea29f411aaf/plugins/midnight-tooling/skills/midnight-debugging/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Aaron Bassett

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: aaronbassett
Original project: https://github.com/aaronbassett/midnight-knowledgebase/blob/8d873d378dc993f3b80e611d44605ea29f411aaf/plugins/midnight-tooling/skills/midnight-debugging/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Product Management, Customer Support
Roles: Backend Developer, DevOps / SRE, Product Manager, QA / Test Engineer, Technical Support
Specialties: Backend, DevOps
Tools: Docker, Compact
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 00c56dedd39ae30c04e3b5a9cb5f6f2dc072c2c5db65ad11da7056969ee94429