Troubleshooting Guide - Common Testship Issues and Solutions

Common Issues

Installation Issues

Cannot find module ‘testship’

Problem: After installing, running testship results in “command not found” or similar error.

Solutions:

1. Use npx instead (recommended):

   npx @blockchain-hq/testship@latest start

   This bypasses global installation issues entirely and always uses the latest version.

2. Verify installation:

   npm list -g @blockchain-hq/testship

3. Reinstall globally:

   npm install -g @blockchain-hq/testship

4. Check npm global path:

   npm config get prefix

   Ensure this directory is in your PATH.

Permission errors during installation

Problem: EACCES or permission denied errors when installing globally.

Solutions:

1. Use a Node version manager (recommended):

   • Install nvm or fnm
   • Reinstall Node.js through the version manager

2. Fix npm permissions:

   mkdir ~/.npm-global
   npm config set prefix '~/.npm-global'
   echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
   source ~/.bashrc

3. Use sudo (not recommended):

   sudo npm install -g @blockchain-hq/testship

Project Detection Issues

”No Anchor project found”

Problem:

Error: No Anchor project found. Please run from Anchor project directory.

Checklist:

• ✅ You’re in the root directory of your Anchor project
• ✅ Anchor.toml file exists in the current directory
• ✅ Not in a subdirectory like programs/ or tests/

Solution:

# Navigate to project root
cd /path/to/your/anchor/project

# Verify Anchor.toml exists
ls Anchor.toml

# Now start TestShip
npx @blockchain-hq/testship@latest start

“No IDL directory found”

Problem:

Error: No IDL directory found.

Please run: anchor build

Causes:

• Program hasn’t been built yet
• Build failed previously
• target/ directory was deleted

Solution:

# Build your Anchor program
anchor build

# Verify IDL was generated
ls target/idl/

# Start TestShip
npx @blockchain-hq/testship@latest start

“No IDL files found”

Problem:

Error: No IDL files found.

Please run: anchor build

Causes:

• Build completed but didn’t generate IDL
• Program has compilation errors
• IDL generation was skipped

Solution:

# Clean and rebuild
anchor clean
anchor build

# Check for errors in the build output
# Fix any compilation errors in your program

# Verify IDL exists
ls target/idl/*.json

# Start TestShip
npx @blockchain-hq/testship@latest start

Server Issues

Port already in use

Problem: Port 3000 is already occupied by another service.

Solution:

Use a different port:

npx @blockchain-hq/testship@latest start --port 8080

Or find and kill the process using port 3000:

# macOS/Linux
lsof -ti:3000 | xargs kill -9

# Windows
netstat -ano | findstr :3000
taskkill /PID <PID> /F

Browser doesn’t open automatically

Problem: TestShip starts but browser doesn’t open.

Solution:

Manually open your browser and navigate to:

http://localhost:3000

Or the port you specified:

http://localhost:8080

UI shows “Cannot connect to server”

Problem: Browser opens but shows connection error.

Checklist:

1. Check if the server is actually running in the terminal
2. Verify no errors in the terminal output
3. Try refreshing the browser
4. Check the correct port is being used

Solution:

# Stop the server (Ctrl+C)
# Restart
npx @blockchain-hq/testship@latest start
# or if installed globally
testship start

IDL Issues

IDL fails to load in UI

Problem: UI loads but shows “Error loading IDL” or similar message.

Causes:

• IDL file is corrupted
• IDL has invalid JSON syntax
• File permissions issue

Solution:

1. Verify IDL is valid JSON:

   cat target/idl/your_program.json | jq .

2. Rebuild program:

   anchor clean
   anchor build

3. Check file permissions:

   ls -la target/idl/

IDL doesn’t update after code changes

Problem: Made changes to program but UI shows old version.

Solution:

1. Rebuild your program:

   anchor build

2. Restart TestShip:

   # Stop server (Ctrl+C)
   npx @blockchain-hq/testship@latest start

3. Hard refresh browser:

   • Chrome/Firefox: Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
   • Safari: Cmd+Option+R

Tip

With Hot Reloading enabled (coming soon), the UI will automatically update when you rebuild your program.

Multiple Programs

Wrong program is selected

Problem: TestShip is testing the wrong program from your workspace.

Solution:

When you start TestShip, you’ll see a selection prompt if multiple programs exist:

$ npx @blockchain-hq/testship@latest start
? Found multiple Anchor programs. Select one:
❯ program_one
  program_two
  program_three

Use arrow keys to select the correct program.

Program doesn’t appear in selection

Problem: Expected program isn’t listed in the selection menu.

Causes:

• Program wasn’t built
• IDL wasn’t generated
• Program name mismatch

Solution:

1. List your programs:

   ls target/idl/

2. Verify program in Anchor.toml:

   [programs.localnet]
   your_program = "YourProgramID111111111111111111111111111"

3. Build specific program:

   anchor build -p your_program

Getting Help

If you’re still experiencing issues:

1. Check the Terminal Output: Look for detailed error messages
2. Verify Prerequisites: Ensure Rust, Solana CLI, and Anchor are properly installed
3. Update Dependencies: Make sure you’re using the latest version of TestShip
4. Community Support:
   • Follow us on X: @testshipxyz
   • Visit: testship.xyz

Reporting Bugs

When reporting issues, please include:

• TestShip version (testship --version)
• Node.js version (node --version)
• Anchor version (anchor --version)
• Operating system
• Complete error message
• Steps to reproduce

Next Steps

• Review CLI Reference
• Check API Reference
• Read the Quick Start Guide