Skip to main content
Version: Canary 🚧

Fix version mismatch errors

Learn how to resolve version compatibility issues between Midnight components that cause build failures and runtime errors.

Understanding version mismatches​

Midnight consists of multiple components that must work together in compatible versions:

  • Compact compiler
  • Runtime libraries (@midnight-ntwrk/compact-runtime, @midnight-ntwrk/ledger, etc.)
  • Proof server
  • Indexer (if used)

When these components are out of sync, you may encounter build errors, deployment failures, or runtime issues.

Check the compatibility matrix

Always refer to the official release compatibility matrix to verify which versions work together.

Check your current versions​

Identify which components need updating.

1

Check the compiler version​

compact --version

Compare the output with the compatibility matrix.

2

Check runtime package versions​

npm list @midnight-ntwrk/compact-runtime
npm list @midnight-ntwrk/ledger
npm list @midnight-ntwrk/zswap

All runtime packages should use the same version number.

3

Check proof server version​

If running the proof server using Docker:

docker ps | grep proof-server
docker logs [proof-server-container-id] | head -20

Look for version information in the startup logs.

4

Compare versions with the compatibility matrix​

Review the release compatibility matrix and verify your versions are compatible.

All components show compatible versions according to the official matrix.

Align component versions​

Update components to compatible versions using the official compatibility matrix.

1

Consult the compatibility matrix​

Review the release compatibility matrix to find compatible versions for:

  • Compact compiler
  • Runtime packages
  • Proof server
  • Indexer (if used)
2

Update runtime packages​

Update your package.json with compatible versions from the matrix:

package.json
{
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "x.x.x",
    "@midnight-ntwrk/ledger": "x.x.x",
    "@midnight-ntwrk/zswap": "x.x.x",
    "@midnight-ntwrk/wallet": "x.x.x"
  }
}

Install the updated packages:

npm install
3

Update proof server​

If using Docker, update your container image to a compatible version:

# Stop current container
docker-compose down

# Update docker-compose.yml with compatible version
# Then restart
docker-compose up -d
4

Update the compiler​

Download and install the compatible compiler version from the Compact releases.

Verify installation:

compact --version
5

Recompile contracts​

After updating components, recompile your smart contracts:

# Clean old artifacts
rm -rf contract/*.cjs contract/*.prover contract/*.verifier

# Recompile using direct compact command
compact compile src/contract.compact contract/
Keep components in sync

When updating any component, check the compatibility matrix and update all related components together to maintain compatibility.

Lock exact versions​

Prevent automatic version updates that could break compatibility.

1

Use exact version numbers​

In your package.json, specify exact versions without range operators:

package.json
{
  "dependencies": {
    "@midnight-ntwrk/compact-runtime": "x.x.x",
    "@midnight-ntwrk/ledger": "x.x.x"
  }
}
Avoid version ranges

Don't use ^x.x.x or ~x.x.x. Always specify exact versions like x.x.x to prevent unexpected updates.

2

Use npm ci for installations​

Use npm ci instead of npm install for reproducible builds:

# Clean install from lock file
rm -rf node_modules
npm ci

This installs exact versions from package-lock.json.

3

Document your versions​

Create a VERSIONS.md file documenting your component versions:

VERSIONS.md
# Component Versions

Last verified: 2025-10-17

## Versions in Use

- Compact compiler: x.x.x
- Runtime packages: x.x.x
- Proof server: x.x.x
- Node.js: xx.x.x

## Compatibility Reference

See: /relnotes/support-matrix

Platform-specific considerations​

Ensure all components are properly installed and accessible:

# Check compiler location
which compact

# Verify Node.js version
node --version

Create a version check script​

Automate version checking with this script:

check-versions.sh
#!/bin/bash

echo "=== Midnight Version Check ==="
echo ""

echo "Compiler:"
compact --version || echo "❌ Compiler not found"
echo ""

echo "Runtime packages:"
npm list --depth=0 | grep @midnight-ntwrk || echo "❌ No Midnight packages found"
echo ""

echo "Node.js:"
node --version
echo ""

echo "⚠️  Compare these versions with:"
echo "/relnotes/support-matrix"

Run the check:

chmod +x check-versions.sh
./check-versions.sh

Backup before upgrading​

Always backup your project before upgrading components:

# Back up package.json
cp package.json package.json.backup

# Back up contract artifacts
cp -r contract contract-backup

# Commit current state to git
git add -A
git commit -m "Backup before version upgrade"

Verify after updates​

After aligning versions, confirm everything works:

# Test compilation
compact compile src/contract.compact contract/

# Run tests
npm test

# Check for errors
docker logs [proof-server-container-id]

Common mistakes to avoid​

caution
  • Don't mix version ranges - Use exact versions only
  • Don't update one component - Update all related components together
  • Don't skip the compatibility matrix - Always verify compatibility first
  • Don't forget to recompile - Recompile contracts after compiler updates

Get help​

If version issues persist:

  1. Check the compatibility matrix: Release compatibility matrix
  2. Review release notes: Check for breaking changes in component updates
  3. Ask for help: Post in #developer-support on Discord with your version details
Related guides

Install Development Tools​

  • Installation guide - Comprehensive setup guide covering the Lace wallet, test tokens, Compact compiler, and proof server installation

  • Build a DApp tutorial - Detailed instructions for building your first DApp with the Compact developer tools

  • Using Midnight tutorial - Prerequisites and setup instructions for connecting to the Midnight network

Configure Your Environment​

Reference​

These guides cover everything from basic prerequisites to advanced version management for maintaining a stable development environment.