Common Installation Issues

Solutions to the most common problems users encounter when installing Zod.

Issue: “Command not found: zod”

Problem

After installation, running npx zod returns “command not found”.

Solutions

Solution 1: Verify Installation

npm list @zod/harness

If not installed, run:

npm install @zod/harness

Solution 2: Check Node Version

node --version

Zod requires Node.js 18 or higher. Upgrade if needed:

nvm install 18
nvm use 18

Solution 3: Clear npm Cache

npm cache clean --force
npm install @zod/harness

Issue: “Permission denied” errors

Problem

Installation fails with permission errors.

Solutions

Solution 1: Use npx Instead of global install, use npx:

npx zod init

Solution 2: Fix npm Permissions

sudo chown -R $(whoami) ~/.npm

Solution 3: Use a Node Version Manager

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18

Issue: Dependency conflicts

Problem

Installation fails due to conflicting dependencies.

Solutions

Solution 1: Update Dependencies

npm update
npm install @zod/harness

Solution 2: Clean Install

rm -rf node_modules package-lock.json
npm install

Solution 3: Use —legacy-peer-deps

npm install @zod/harness --legacy-peer-deps

Issue: “Module not found” errors

Problem

Running Zod throws module not found errors.

Solutions

Solution 1: Reinstall Dependencies

rm -rf node_modules
npm install

Solution 2: Check imports Ensure your imports are correct:

import { Agent } from '@zod/harness'; // Correct

Issue: Slow installation

Problem

Installation takes an unusually long time.

Solutions

Solution 1: Use Bun instead of npm

curl -fsSL https://bun.sh/install | bash
bun install @zod/harness

Bun is significantly faster than npm.

Solution 2: Check Network

• Ensure stable internet connection
• Try a different network if possible
• Check if npm registry is accessible:

npm ping

Still Having Issues?

If none of these solutions work:

1. Check our GitHub Issues
2. Create a new issue with:
   • Your OS and version
   • Node.js version
   • Full error message
   • Steps to reproduce

We’re here to help!