"Troubleshooting Guide\n\nCommon issues and solutions for model-fallback-skill.\n\n## Table of Contents\n\n- Installation Issues\n- Configuration Issues\n- Runtime Issues\n- Health Check Issues\n- Fallback Issues\n\n## Installation Issues\n\n### Permission Denied on install.sh\n\nProblem: bash: ./install.sh: Permission denied\n\nSolution:\nbash\nchmod +x install.sh\n./install.sh\n\n\n### Python Not Found\n\nProblem: python3: command not found\n\nSolution:\nbash\n# Check if python is installed\nwhich python3\n\n# Install Python 3.8+ (macOS)\nbrew install python3\n\n# Install Python 3.8+ (Ubuntu/Debian)\nsudo apt-get install python3\n\n\n### nanobot Config Not Found\n\nProblem: Error: nanobot config not found at ~/.nanobot/config.json\n\nSolution:\nbash\n# Check if nanobot is installed\nwhich nanobot\n\n# Verify config location\nls -la ~/.nanobot/config.json\n\n# If using custom config path, update scripts with correct path\n\n\n## Configuration Issues\n\n### No Fallback Models Configured\n\nProblem: Health check shows "No fallback models configured"\n\nSolution:\n\nAdd fallback models to your nanobot config:\njson\n{\n \"agents\": {\n \"defaults\": {\n \"model\": \"minimax/m2.5\",\n \"fallbackModels\": [\n \"openrouter/anthropic/claude-3.5-sonnet\",\n \"openrouter/glm-4.7\"\n ]\n }\n }\n}\n\n\n### API Key Missing\n\nProblem: Error: API key not configured for provider\n\nSolution:\n\nAdd the API key to your nanobot config:\njson\n{\n \"providers\": {\n \"minimax\": {\n \"apiKey\": \"your-api-key-here\"\n },\n \"openrouter\": {\n \"apiKey\": \"your-openrouter-key-here\"\n }\n }\n}\n\n\n## Runtime Issues\n\n### Health Check Not Running\n\nProblem: Health check process not found\n\nSolution:\nbash\n# Check if health check is running\npython3 scripts/health-check.py status\n\n# Start health check\npython3 scripts/health-check.py start\n\n# Check logs for errors\ntail -f ~/.nanobot/logs/model-health.log\n\n\n### nanobot Not Running Under Wrapper\n\nProblem: Fallback can't restart nanobot\n\nSolution:\n\nMake sure nanobot is running under the wrapper:\nbash\n# Stop current nanobot\npkill -f \"nanobot gateway\"\n\n# Start with wrapper\n~/nanobot-wrapper.sh\n\n\n### Restart Trigger Not Working\n\nProblem: Restart trigger created but nanobot doesn't restart\n\nSolution:\nbash\n# Verify wrapper is running\nps aux | grep nanobot-wrapper\n\n# Check trigger file\nls -la /tmp/nanobot-restart\n\n# Manually trigger restart\ntouch /tmp/nanobot-restart && pkill -f \"nanobot gateway\"\n\n\n## Health Check Issues\n\n### Health Check Always Fails\n\nProblem: Health check reports failures for all models\n\nSolution:\n\n1. Check network connectivity:\nbash\nping api.minimax.chat\nping openrouter.ai\n\n\n2. Verify API keys are valid\n\n3. Adjust thresholds in health-check.py:\npython\nMAX_RESPONSE_TIME = 60 # Increase from 30\nMAX_TIMEOUT_RATE = 0.3 # Increase from 0.2\nMAX_ERROR_RATE = 0.15 # Increase from 0.1\n\n\n### Health Check Too Frequent\n\nProblem: Health check running too often\n\nSolution:\n\nAdjust the interval in health-check.py:\npython\nCHECK_INTERVAL = 600 # Change from 300 (10 minutes instead of 5)\n\n\n## Fallback Issues\n\n### Fallback Not Triggering\n\nProblem: Model fails but fallback doesn't activate\n\nSolution:\n\n1. Check health check is running:\nbash\npython3 scripts/health-check.py status\n\n\n2. Check logs for errors:\nbash\ntail -f ~/.nanobot/logs/model-health.log\ntail -f ~/.nanobot/logs/model-fallback.log\n\n\n3. Manually trigger fallback to test:\nbash\npython3 scripts/fallback-trigger.py trigger --reason \"Test\"\n\n\n### All Models Failed\n\nProblem: All models in fallback chain failed\n\nSolution:\n\n1. Check API keys are valid\n2. Verify network connectivity\n3. Check provider status pages\n4. Add more fallback models to config\n5. Consider using a different provider\n\n### Wrong Model Selected\n\nProblem: Fallback selected wrong model\n\nSolution:\n\nVerify fallback chain order in config:\nbash\npython3 scripts/fallback-trigger.py status\n\n\nAdjust order in config:\njson\n{\n \"fallbackModels\": [\n \"first-choice-model\",\n \"second-choice-model\",\n \"third-choice-model\"\n ]\n}\n\n\n## Getting Help\n\nIf you're still having issues:\n\n1. Check the logs:\n - ~/.nanobot/logs/model-health.log\n - ~/.nanobot/logs/model-fallback.log\n\n2. Run diagnostics:\n bash\n python3 scripts/health-check.py diagnose\n \n\n3. Open an issue on GitHub:\n https://github.com/capt-marbles/model-fallback-skill/issues\n\n4. Include in your issue:\n - Python version\n - nanobot version\n - Config file (redact API keys)\n - Relevant log entries\n - Steps to reproduce"]