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: I typed /help but nothing happened?
A: Zcrafter uses a Command Palette for actions, similar to VS Code. Press Ctrl+K 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+K.
- 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.
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.