Troubleshooting & FAQ

Encountering an issue? This guide covers the most common problems and their solutions.

Frequently Asked Questions

Q: How do I connect to my mainframe?

A: Press Ctrl+M (or Ctrl+\) at any time to open the Connection Manager. You will need your mainframe's Hostname (IP), Port (usually 10443), Username, and Password.

Q: Why does the Mainframe dialog keep popping up?

A: Zcrafter tries to ensure you have a valid connection context. If you want to work offline or just use the AI for general coding questions, simply press Esc to dismiss the dialog.

Q: How do I switch AI models?

A: Press Ctrl+O to cycle through your available models. This is useful if you want to save credits by using a smaller model for simple questions, or switch to a more powerful model like Claude 3.5 Sonnet for complex debugging.

Q: Where is my API key stored?

A: Your API key is stored securely on your local machine in ~/.Zcrafter.json. It is never sent to our servers. Zcrafter connects directly to the AI provider (OpenAI, Anthropic, etc.) from your computer.

Q: I typed /help but nothing happened?

A: Zcrafter uses a Command Palette for actions, similar to VS Code. Press Ctrl+D to see all available commands like "Reset API Key", "Clear Screen", and "Feedback".

Common Error Codes

401 Unauthorized (AI Provider)

Symptoms: The AI responds with "Invalid API Key" or "401 Unauthorized". Cause: Your API key is incorrect, expired, or has no credits left. Solution:

Press Ctrl+D.
Select Reset API Key.
Restart Zcrafter and enter a valid key.

ECONNREFUSED (Mainframe)

Symptoms: "Connection refused" or "Timeout" when trying to list datasets or submit jobs. Cause: Zcrafter cannot reach your mainframe. Solution:

VPN: Ensure you are connected to your corporate VPN.
Port: Verify you are using the correct z/OSMF port (default is 10443).
Status: Ask your system administrator if z/OSMF is running.

x509: Certificate Signed by Unknown Authority

Symptoms: Certificate error when connecting to mainframe. Cause: Your mainframe uses a self-signed SSL certificate, which is common in development environments. Solution:

Press Ctrl+M to open the connection dialog.
Navigate to the [ ] Skip SSL Verify checkbox.
Press Space to check it.
Try connecting again.

Installation & Updates

Global Version Mismatch

Problem: You installed the latest version via npm install -g zcrafter, but zcrafter --version still shows an older version.

Cause: This usually happens when an old binary exists in /usr/local/bin (or another directory in your PATH) that takes precedence over the npm-installed binary, or if the npm binary wasn't linked correctly.

Solution:

Check which binary is being used:
```
which zcrafter
```
Remove the old binary: If the output is /usr/local/bin/zcrafter (and it's not a symlink to the npm package), remove it:
```
sudo rm /usr/local/bin/zcrafter
```

Link the new binary: Create a symbolic link to the npm-installed binary.

macOS/Linux:

# Find where npm installed the package
NPM_BIN=$(npm config get prefix)/lib/node_modules/zcrafter/bin/zcrafter
 
# Link it to /usr/local/bin
sudo ln -s "$NPM_BIN" /usr/local/bin/zcrafter

Verify:
```
zcrafter --version
```

Clearing Old Versions & Forcing Latest Version

Problem: You're stuck on an old version and want to completely clear your system and install the latest version.

Solution - Complete Clean Installation:

Check current version and location:
```
zcrafter --version
which zcrafter
```

Remove all existing zcrafter binaries:

# Remove global npm package
sudo npm uninstall -g zcrafter
 
# Remove symlink in /usr/local/bin
sudo rm /usr/local/bin/zcrafter
 
# Remove any standalone binaries
rm ~/zcrafter  # if you have it in home directory
rm ./zcrafter  # if you have it in current directory

Clear npm cache:
```
npm cache clean --force
```
Install latest version:
```
npm install -g zcrafter
```

Create proper symlink:

# Find npm installation path
NPM_BIN=$(npm config get prefix)/lib/node_modules/zcrafter/bin/zcrafter
 
# Create symlink (if not automatically created)
sudo ln -sf "$NPM_BIN" /usr/local/bin/zcrafter

Verify installation:

zcrafter --version
which zcrafter
ls -la /usr/local/bin/zcrafter

Alternative - Force Update Symlink: If npm shows the latest version but your global command doesn't:

# macOS ARM (M1/M2/M3)
sudo ln -sf ~/.npm-global-user/lib/node_modules/zcrafter/bin/zcrafter /usr/local/bin/zcrafter
 
# macOS Intel or standard npm prefix
sudo ln -sf $(npm config get prefix)/lib/node_modules/zcrafter/bin/zcrafter /usr/local/bin/zcrafter

Automatic Upgrade (Recommended)

New in v3.1.40: Zcrafter now has an automatic upgrade command!

Usage:

zcrafter upgrade

This command will:

Check for the latest version on npm
Automatically install the update
Fix symlinks if needed
Verify the installation

What You'll See:

$ zcrafter upgrade
Checking for updates...
✓ New version available: v3.1.40 (current: v3.1.38)
Installing update...
✓ Successfully upgraded to v3.1.40!
 
Restart your terminal or run 'hash -r' to use the new version.

Note: The upgrade command may prompt for your password (sudo) if needed.

Permission Errors (EACCES)

Problem: npm install -g zcrafter fails with Error: EACCES: permission denied.

Cause: Your npm cache or global directories are owned by root, preventing your user from writing to them.

Solution:

Fix ownership of npm directories:
```
sudo chown -R $(whoami) ~/.npm
```
Retry installation:
```
npm install -g zcrafter
```
Alternative (Recommended): Use a Node Version Manager (like nvm) to avoid using sudo for npm packages.

Runtime Issues

"Command not found: zcrafter"

Problem: You installed the CLI, but the terminal says the command doesn't exist.

Cause: The directory where npm installs global binaries is not in your system's PATH.

Solution:

Find your npm bin directory:
```
npm config get prefix
```
(Usually /usr/local or ~/.npm-global)
Add to PATH: Add the bin folder inside that prefix to your shell configuration (.zshrc, .bashrc, etc.).
```
# Example for .zshrc
export PATH=$PATH:$(npm config get prefix)/bin
```
Restart Terminal: Close and reopen your terminal window.

"no such file or directory" (Local Development)

Problem: Trying to run ./zcrafter in the source directory fails.

Cause: You haven't built the binary from the Go source code yet.

Solution:

Build the binary:
```
go build -o zcrafter .
```
Run:
```
./zcrafter
```

Connectivity Issues

Mainframe Connection Failed

Problem: The CLI cannot connect to the mainframe ("z/OSMF REST API Error" or timeouts).

Solution:

Check VPN/Network: Ensure you are connected to the Marist VPN or the required network for your mainframe access.
Verify Status: Check if the z/OSMF service is running on the mainframe.
Check Credentials:
- Run zowe auth list to see your profiles.
- Update credentials if expired: zowe auth login (if using Zowe V3) or check your zowe.config.json.
Debug Mode: Run Zcrafter with debug logging enabled (if available) or check the logs in ~/.zcrafter/logs/.

AI & Model Issues

Model Not Responding

Problem: The AI assistant is silent or returns errors.

Solution:

Check API Key: Ensure your API key (OpenAI, Anthropic, etc.) is valid and set in your environment variables or configuration.
Rate Limits: You may have exceeded your rate limit for the selected provider. Try switching models (Ctrl+O).
Internet Connection: The CLI requires an active internet connection to reach AI providers.

Advanced Debugging

If you are still stuck, you can enable debug mode to see exactly what's happening under the hood.

Run with Debug Flag:
```
zcrafter --debug
```
Check Logs: Logs are written to ~/.Zcrafter/debug.log. You can view this file to see detailed error messages.

Note: Never share your debug log publicly as it may contain sensitive information.

Advanced Configuration Advanced Troubleshooting