Advanced Troubleshooting

Advanced Troubleshooting

This guide covers deeper troubleshooting steps for complex issues that aren't resolved by the basic troubleshooting guide.

Debug Mode

The first step in diagnosing any complex issue is to enable Debug Mode.

zcrafter --debug

Or set the environment variable:

export ZCRAFTER_DEBUG=true

This will output verbose logs to the terminal and/or a log file (usually in .Zcrafter/debug.log). Look for lines starting with DEBUG or ERROR.

Common Error Codes

z/OSMF Errors

  • 401 Unauthorized: Incorrect username or password. Also happens if your password has expired.
  • 403 Forbidden: You don't have permission to access the requested resource (dataset or job). Check your RACF/ACF2/TopSecret permissions.
  • 500 Internal Server Error: An issue on the mainframe side. Check if z/OSMF is running correctly.
  • Connection Refused: The CLI cannot reach the mainframe. Check your VPN, firewall, or if the port is correct.

AI Provider Errors

  • 401 Invalid API Key: Your API key is incorrect or expired.
  • 429 Rate Limit: You've sent too many requests too quickly. Wait a moment or check your quota.
  • 503 Service Unavailable: The AI provider is down. Check their status page.

Network Diagnostics

If Zcrafter cannot connect to the mainframe or AI provider:

  1. Check Connectivity:

    ping zos.example.com
ping openrouter.ai

  2. Test Ports:

    nc -zv zos.example.com 10443

  3. Proxy Settings: If you are behind a corporate proxy, ensure your HTTP_PROXY and HTTPS_PROXY environment variables are set correctly.

Log Files

Zcrafter writes logs to the data directory (default ~/.Zcrafter).

  • debug.log: Contains detailed execution logs.
  • messages/: Stores conversation history.

Reviewing debug.log is often the best way to understand why a specific action failed.

Troubleshooting