Troubleshooting

Troubleshooting

Common issues and solutions when using Zcrafter.

Installation Issues

Permission Errors (EACCES)

Problem:

npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules

Solution:

Use sudo when installing:

sudo npm install -g zcrafter

Node.js Version Too Old

Problem:

Error: Requires Node.js >= 16.0.0

Solution:

Upgrade Node.js by downloading the latest LTS version from nodejs.org.

Command Not Found

Problem:

zcrafter: command not found

Solutions:

  1. Verify installation completed:
npm list -g zcrafter
  1. Reinstall Zcrafter:
npm uninstall -g zcrafter
npm install -g zcrafter
  1. Restart your terminal after installation

API Key Issues

Key not set

Problem:

Error: API key required

Solution: Set your key:

export OPENROUTER_API_KEY="your-api-key"

Then restart your terminal or run source ~/.zshrc if you added it to your profile.

Invalid API key

Problem:

Error: Invalid API key

Solution: Generate a new key from openrouter.ai and set it again:

export OPENROUTER_API_KEY="new-key"

Usage Issues

429 or rate limit errors

Problem:

Error: Too Many Requests (429)

Solutions:

  1. Try again in a minute
  2. Use shorter prompts
  3. Select a different model

Network Errors

Problem:

Error: Network request failed
Error: ECONNREFUSED

Solutions:

  1. Check your internet connection
  2. Verify you can access other websites
  3. Check if your firewall is blocking the connection
  4. Try again in a few moments

Slow Responses

Problem: Zcrafter takes too long to respond

Solutions:

  1. Check your internet connection speed
  2. Use shorter, more specific prompts
  3. Try again during off-peak hours
  4. If the problem persists, the service may be experiencing high load

Interactive Mode Issues

Terminal Display Issues

Problem: Garbled text or weird characters

Solutions:

  1. Try a different terminal application
  2. Update your terminal software to the latest version
  3. Restart your terminal

Commands Not Working

Problem: Typed commands don't execute

Solutions:

  1. Check for typos:
/hlep   (incorrect)
/help   (correct)
  1. Make sure there are no spaces after the slash:
/ login  (incorrect)
/login   (correct)
  1. Try pressing Enter after the command

Can't Exit

Problem: /exit doesn't work

Solutions:

  1. Try typing:
/quit
  1. Press Ctrl+C twice
  2. Close the terminal window

Common Error Messages

ENOSPC

Problem:

Error: ENOSPC: no space left on device

Solution:

Free up disk space on your computer. Delete unnecessary files or move files to external storage.

EPERM

Problem:

Error: EPERM: operation not permitted

Solution:

Use sudo when installing:

sudo npm install -g zcrafter

Getting Additional Help

If you can't resolve your issue:

  1. Check this documentation

  2. Run in debug mode

Type:

zcrafter --debug

This provides additional error information that may help identify the problem.

  1. Restart and try again

    • Close your terminal
    • Open a new terminal window
    • Try the command again

  2. Reinstall Zcrafter

If all else fails, try reinstalling:

npm uninstall -g zcrafter
npm install -g zcrafter

Tips for Preventing Issues

  1. Keep Node.js updated: Regularly update to the latest LTS version
  2. Be specific with questions: Clear questions get better responses
  3. Keep Zcrafter updated: Run npm update -g zcrafter periodically

Next Steps

Slash Commands